-
Notifications
You must be signed in to change notification settings - Fork 405
Documentation
The official documentation for Selenium can be found at http://www.seleniumhq.org/
- Communicate to the others what your plans are and what you're currently working on to be synchronized with other team members
- Try to avoid huge reformatting/restructuring to reduce merge effort
- Update regularly to always be on the bleeding edge and to be able to review others' changes
- Commit only changes you're satisfied with i.e. take a look over your changes prior to submitting them to the repository
We use reStructured Text for structuring and shaping the documentation, therefore it is required to know the basics of it by reading
- http://docutils.sourceforge.net/docs/user/rst/quickref.html (short, with lots of examples)
- http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html (longer, more advanced)
The RST files written by the team are parsed using Sphinx, a python documentation tool that takes care of the styling and superficial stuff. To do this manually, you must first install Sphinx (which also needs python)
Here you'll find some rules we must follow to keep the documentation source files as clean as possible.
- Try to keep lines of no more that 80 columns, this way most text editors will be able to render the rst file in the same way, and will save us the annoyance of unending lines. The final html will be rendered as expected as the parser joins all consecutive lines to a single paragraph until the next blank line.
- Don't add extra spaces. The parser removes duplicated spaces anyway, but it's better to keep the source rst files as clean as possible.
- Don't use unicode characters, like ¶ ñ á or even �� and � (double dashes). They sometimes are parsed correctly, but in some environment they don't, which brings more problems than advantages...
Most of this is simply lifted from the Python documentation.
- Use italics when defining a new term for the first time.
- Capitalize and hyphenate each of the Selenium components: Selenium-IDE, Selenium-RC, Selenium-Grid, Selenium-Core. Additionally, "Selenium" should be spelled out in full and not abbreviated to "Sel" in the official documentation.
- JavaScript should be spelt with CamelCase, i.e. capital 'J' capital 'S.'
- URLs, file directories, file names, and selenium commands written inline should be monospaced using ``mono``
- Code Snippets should be prefaced with ".. code-block:: <language>" where <language> is the programming language
- Command line input and output should be a block, indented and prefaced with two colons. See the end of the Selenium-RC chapter for reference.
- Linux command line should be a code block prefaced with ".. code-block:: bash"
You can apply certain style to text, just by putting some marks on it, here are some examples: **bold**, *italics*, ``monospaced text``.
To make links you have 4 alternatives:
Easy but cluttered way: `Text linking <http://url.linked.com>\`_
Common way: `Text linking`_ then you can write more text and you can call the link anywhere you want like now `Text linking`_ Then, when you have some free space, you can write the target to that link (see the end of the file for the target linking).
Titles are link targets also! All you have to do is put the title followed with an underscore like in `Some rules`_ or `Tips_`
Links within the documentation but on other pages can be created by using the :ref: syntax. First, create a reference to the section you want by putting .. _sectionName-reference: just before the text. There are three important parts to this: The ".." at the beginning tells Sphinx not to display the output, the underscore denotes this is a reference (similar to method 3) and the colon (:) tells Sphinx that the following content is being referenced. Then, to create the link write :ref:\Section Title `` "Section Title" will be displayed in the output and linked to the section named.
Off course, the next point to go from here if you find any problems is: http://docutils.sourceforge.net/docs/user/rst/quickref.html or http://sphinx.pocoo.org/rest.html