Documentation Infrastructure

Basic knowledge

Be sure to understand chapter 1 "Fundamental Concepts" of the SVN book.

Subversion client

For non-developers: The recommended way is to install a desktop-integrated client from http://subversion.tigris.org/links.html#desktop-integrations.

For developers: No recommendation.

Repository

According to your interest/profile choose one the following two URLs to be used for checkout in the Subversion client of your choice

Only working on the RST files: https://svn.openqa.org/svn/selenium-core/selenium-website/src/main/rst

Also working on the website: https://svn.openqa.org/svn/selenium-core/selenium-website

Access

In order to be able to commit you need an OpenQA account with the appropriate privileges - if you don't have one already and you're part of the team contact Patrick Lightbody.

Working process

• 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

Documentation markup language

We use reStructured Text for structuring and shaping the documentation, therefore it is required to know the basics of it by reading

• http://jrst.labs.libre-entreprise.org/jrst/en/user/RSTpresentation.html (shorter, concise)
• 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)

Local machine parsing using sphinx

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)

1. First install python
   Already installed on most *NIX. Grab the installer from http://python.org/download/ if you use windows

   Notice: the version of python recommended to install is 2.5.x (latest setuptools windows installer is for version 2.5)

2. Install setuptools (this will allow you to use easy_install on the next step)
   Get the installer from http://pypi.python.org/pypi/setuptools
3. Then install sphinx (run the following on a terminal):

   easy_install Sphinx
   

Finally, to generate the docs. All you have to do is run this on a terminal:

sphinx-build -b html <rest_files_location> <html_destination>

That's it, you should find the files on the html_destination you've chosen (open index.html to see the docs).