DocumentationBuild
When accessing SUMO web space, you will find an index page, and several additional HTML pages. You will also find a link to a wiki, a trac instance, and a blog. In the following, it is described how these documentation parts are build, and mirrored.
After some tries, we decided to work as following:
- The documentation is "developed" within the wiki; the wiki refers to the state of the package as-is within the SVN.
- The HTML documentation is generated from the wiki
Contents |
Documentation Parts
Wiki
scope
- The wiki should include the complete user documentation, as well as finalised developer documents, and any kind of additional documentation as long as it is in a state which can be presented. Incomplete or outdated wiki documents should have the prefix "Purgatory/" and should not be linked from any other documents.
rights
- The rights to edit the wiki are given to known users on request.
backup
- An offline-backup of the wiki is created as part of the linux build. The file <SUMO_HOME> /Makefile.am defines the task wikidump which uses the open source program [httrack] to create an offline-browsable mirror (excluding special pages such as history and discussion). The backup is included in the regular release starting at version 0.13.1.
There are currently two options for looking up information from wiki versions before 0.13.1
- Use the wiki-history for an individual wiki page
- Use the sumo-user.pdf included in older releases. This pdf was compiled from the wiki at the time of the release and should contain most of the wiki content.
HTML pages
scope
- HTML pages contain all information stored in the wiki at the time of the last release.
rights
- HTML pages are generated and uploaded by SUMO developers which have access to the web space.
backup
- No backup is needed, as the source (wiki) is backupped. Additionally, the documentation is a part of the release.
WebLog
scope
- Should include information about current events.
rights
- SUMO developers are responsible for adding items to the blog.
backup
- Missing!!!
trac
scope
- trac is used for planning releases and tracking bugs/other work items.
rights
- SUMO developers are allowed to modify trac.
backup
- Missing!!!
HTML pages generation
Mirroring the wiki
The HTML pages are built from the wiki. All scripts needed are located in <SUMO_HOME>/tools/build.
getWikiPages.py is used to retrieve the HTML-representation of wiki-pages. If started with a parameter, this parameter is assumed to be the name of the page to retrieve. If no parameter is given, getWikiPages.py retrieves the list of all pages, first, from Special::AllPages.
Each of the pages to retrieve is read from the wiki and stripped so that it contains the article HTML only. getWikiPages.py changes the links included in this result and retrieves the embedded images (only the "normal" version, no thumbnails) and saves the resulting HTML with no header/tail into a file located in "mirror" named using the articles' name. The folder "mirror" is generated.
All images found in the read pages are retrieved and stored in "mirror/images".
Generating the HTML template
The HTML template is located in <SUMO_HOME>/tools/build as "index.html". It contains a list of documentation contents which must be adapted. This adaptation is currently done by retrieving the wiki-formatted content of SUMO User Documentation and pasting it into the file "content_user.txt" which is also located in <SUMO_HOME>/tools/build. convertWikiContent.py reads this file and converts it into a HTML-list representation, saved as "out.html". This has then to be pasted into "index.html" between the comments <!-- nav begins --> and <!-- nav ends -->.
Building HTML pages
The last step is to call embedInIndex.py. This script reads all pages stored in "mirror" and inserts their content into "index.html" between the comments <!-- content begins --> and <!-- content ends -->. Links are patched to match the depth of the folder the page is located in.
The images stored in "mirror/images" are copied to "docs/images".