PURPOSE

This script will fetch the Aseba wikidot to retrieve locally
the documentation. It is intended to be used solely by the release manager,
upgrading the documentation just before each release. If this is not your
purpose, please don't commit upstream the result.


INSTALLATION

Python > 2.6 should be installed on your computer.

Moreover, the script invokes HTML-tidy (http://tidy.sourceforge.net/), 
in order to clean up the generated HTML. The script will try to invoke the 'tidy' process.
If different on your system, update the 'tidy' function in wikidot/tools.py.
You can also disable this step, by commenting out the line in wikidot/fetch.py.


USAGE

It is very simple. Just run:

./updatedoc.py

It will perform the following operations:
- Clean the previous run (output directory and files).
- For each language in the map, create a dedicated output directory,
  recursively fetch / convert / clean the documentation, 
  build the doc structure, copy the files to the final directory.
- Generate the Qt Help File, based on the doc structure and file
  listing.
- Remove the old documentation from the Aseba Studio directory,
  and copy the new ones there.

Be careful, it will brutally remove the studio/doc/ directory, so do not
manually edit files there, or your changes will be lost!


CUSTOMIZATION

The important parameters are defined at the top of updatedoc.py. You can
for example change the path to Aseba Studio, update the wikidot links to the
documentation for each language, add another language, or use another CSS.


SOME EXPLANATIONS

The wikidot has a flat structure, so we don't care about the full URL, but just
about the page's name. Each URL is converted to a local-storage name, using the
'urltoname' function located in the wikidot/urltoname.py module. If you want
to change the naming scheme, you can do it there.

Qt is using the QtHelp framework. It needs as input a Qt Help Project file (.qhp),
which is generated by the qthelp.py module. It keeps track of the documentation's
hierarchy, using the wikidot/structure.py module. It uses the breadcrumbs located
on top of each page, in order to build the hierarchy of the documentation. It is
important to keep those breadcrumbs up-to-date, or the package will fail to work
properly.

You can get more help on the Qt Help Framework here:
http://doc.qt.nokia.com/stable/qthelp-framework.html

A potential issue is if a child is parsed before its parent. As the parent does not
yet exist in the tree, the child will fail to get inserted. This will happen if
a link is pointing to the child from an upper level, short-circuiting the legitimate
parent. Either fix the links on the wikidot, either buffering the pages before building
the tree. For now, each page is inserted into the tree from the wikidot/tools.py module.

