Due to the limitations of Python distutils and setuptools not all of the documentation can be build from within setup.py. Most of this has to be done manually. Documentation is provided as follows
| nx2img | manpage and HTML documentation |
| img2nx | manpage and HTML documentation |
| qnx2img | inline help and HTML documentation |
| developers | only HTML documentation |
In order to save time and effort to run several documentation systems in parallel we have decided to do everything with Sphinx.
Manpages are built for nx2img and img2nx. The build is started with
$ python setup.py build_sphinx -bman
which should create the files
img2nx.1
nx2img.1
in build/sphinx/man.
The HTML documentation can be done with
$ python setup.py build_sphinx -bhtml
Which should create new files below build/sphinx/html.
Building the QtHelp documentation is a bit more tricky. First start by running Sphinx with
$ python setup.py build_sphinx -bqthelp
which would result in new files below build/sphinx/qthelp. Aside from the HTML files you will find there
NexusImageTools.qhcp
NexusImageTools.qhp
use the qcollectiongenerator program to create the compressed HTML files and the collection file. Running the program in build/sphinx/qthelp with
$ qcollectiongenerator -o NexusImageTools.qhc NexusImageTools.qhcp
will create two new files
NexusImageTools.qhc
NexusImageTools.qch
where the first one is the help collection and the second one the file with the compressed HTML files. As currently only qnx2img makes use of the Qt help engine these files should be copied to src/nexus_image_tools/qnx2img.
Note
Need a better procedure so that the files are copied automatically to the required location.
Currently we have to update the files manually and copy them to the appropriate source folder.