widelands-dev team mailing list archive

[kaputtnik <somal@xxxxxxxx>]

The proposal to merge lp:~widelands-dev/widelands-website/solitaire_html_documentation into lp:widelands-website has been updated.

Description changed to:

Serve sphinx documentation as html files. This remove unmaintained sphinx-doc. But all features of the produced html could be used (e.g searching).

The main idea is to let sphinx build the html files directly in the media folder of the website and link it from the navigation. So no extra entries for nginx are needed.

To ease up the creation step of the documentation, a management command is implemented which uses an own conf.py for sphinx. To create the documentation one can just write:

./manage.py create_docs

To have a similar look and feel in the created html files, i have added also the needed css and background images to this branch and let sphinx use them, so the main source code for widelands isn't tainted. An example image: https://bugs.launchpad.net/widelands-website/+bug/893275/+attachment/5046332/+files/solitaire_documentation.jpg

The management command let sphinx create the doctrees in the WIDELANDS_SVN_DIR/doc/sphinx/build/doctrees/ but puts the produced html in the folder in  MEDIA/documentation/'. On unix like systems the produced html are served from a symlink called 'html'. This makes it possible to have consistent links during creation of new a documentation:

1. sphinx produces html files in a folder called 'html_temp'
2. switch the link to 'html_temp'
3. remove folder 'current' (if exist)
4. copy 'html_temp' to 'current'
5. switch the link to 'current'
6. remove 'html_temp'

On windows systems (if there are ever some users creating the website in an windows environment...) the step to create the symlink is omitted and 'html_temp' is moved to 'html'

We can do similar with the doxygen created documentation.

I you think this approach is good to go, i will make it work on the alpha site for testing. Since heavy file action is involved (moving, deleting of folders), please read the code of documentation/management/commands/create_docs.py very carefully :-)

For more details, see:
https://code.launchpad.net/~widelands-dev/widelands-website/solitaire_html_documentation/+merge/345460
-- 
Your team Widelands Developers is requested to review the proposed merge of lp:~widelands-dev/widelands-website/solitaire_html_documentation into lp:widelands-website.