Sphinx and RobotML documentation¶
Documentation of this project is created thanks to the Sphinx tool. This tooling is using Python as its underlying framework. It means that it is indepedant of the platform on which you will work (It is more or less true, if you have any problems do send a mail to Serge Stinckwhich in order to ask questions or provide bugs).
It is possible to download the complete Sphinx documentation in acrobat format following http://sphinx.pocoo.org/sphinx.pdf.
Installation of Sphinx¶
In order to install this tool, you have to:
- Install Python: version used by the consortium is 2.7.3 considering documentation generation. You can download it from here choosing your own flavour. This version is verified but it does not mean the others are not working (we are speaaking here of the version 3 branch). 2. Install Sphinx: version used for generating documentation is 1.1.3. Hereafter a screenshot of the website indicating how to install.
Install Sphinx
How to generate with Sphinx¶
There is no graphical console allowing to push any buttons. It is needed to
- open a terminal (process is different with respect to the different OS) 2. verify you have access to sphinx command (PATH to complete and it depends also of the OS used) 3. change location in the folder tree in order to position to the root of the documentation (in PROTEUS distribution case on Linux, it means folder XXX) 4. type hereafter command (if -b option is forgotten, default is html, read documentation for more information)
sphinx-build -b html . destination_directory
- you are now able to consider the result in the destination_directory
ECLIPSE RsT plugin¶
It is possible to install an extension in the eclipse platform in order to manage Sphinx projects. You have to use the editor update site http://resteditor.sourceforge.net/eclipse and then a RsT editor will be accessible. This plugin is not perfect but allows a management of the documentation projects in the same interface where everything else is done.
It is necessary to create a generic project and then create the build command (menu project/properties, then consider the builders choice in the left pane).
how to choose builders index
It is necessary then to create the project customised builder (there is no possibility to do otherwise). Either you create the builder from scratch (use the New buider button) or you edit existing buider (use the edit button after selecting the builder to edit).
how to create customised builder
At this step, if you installed Sphinx, you are able to specify the command to launch when building the project. There are subtleties with respect to the different OS and what is shown concerns MacOS and Linux but is easily adaptable to Windows OS.
how to customise builder