Building documentation with qidoc¶
qidoc
supports two documentation tools:
- Doxygen
- sphinx
In the following tutorial, you will learn how to configure
qidoc
, build the documentation and open it.
Table of Contents
Configuring qidoc¶
Using doxygen¶
Suggested layout:
<worktree>
|_ libfoo
|__ qiproject.xml
|__ foo
| |__ foo.h
|__ foo.dox
|__ Doxyfile
Here what the files would look like
<!-- libfoo/qiproject.xml -->
<project version="3" >
<!-- used by qibuild to build your library -->
<qibuild name="libfoo" />
<!-- used by qidoc to build the Doxygen documentation -->
<qidoc name="libfoo-dox" type="doxygen" />
</project>
# libfoo/dox/Doxfile
INPUT=. foo/
(No need for OUTPUT
or GENERATE_*
options, they will be set
by qidoc
automatically)
Using sphinx¶
Suggested layout:
<worktree>
|_ libfoo
|__ qiproject.xml
|__ foo
| |__ foo.h
|__ doc
|_ qiproject.xml
|_ source
|_ conf.py
|_ index.rst
This time you have to tell the qiproject.xml
in libfoo
that there is
a sphinx doc project in the doc
subfolder:
<!-- in libfoo/qiproject.xml -->
<project version="3">
<qibuild name="libfoo" />
<project src="doc" />
</project>
<!-- in libfoo/doc/qiproject.xml -->
<project version="3">
<qidoc name="libfoo" type="sphinx" />
</project>
Building documentation¶
This is done with the qidoc build
command.
As for the qibuild
tool, you can either specify the name
of the doc project, or go to a subdirectory of the documentation project.
For instance, in our sphinx
example:
cd libfoo/doc
qidoc build
# or:
qidoc build libfoo
The resulting html
files will be found in a build-doc
folder, next
to the qiproject.xml
file.
Browsing the documentation¶
You can then see the results in your browser by running qidoc open
If you wish to share your documentation and you have
~/public/html
directory served by a web server, you can run:
qidoc install ~/public/html
Adding templates¶
Sometimes you want to share configuration across several doc projects. To do this you can put all the common configuration in a ‘template’ project.
Layout is:
<worktree>
|_ doc
|_ templates
|_ qiproject.xml
|_ sphinx
| |_ conf.in.py
| |__ _themes
| |_ mytheme
| |_ theme.conf
| |_ layout.html
|_ doxygen
| |_ Doxyfile.in
| |_ doxygen.css
| |_ footer.html
| |_ header.html
|_ doc_proj1
|_ doc_proj2
<!-- in doc/templates/qiproject.xml -->
<project version="3">
<qidoc type="template" />
</project>
# in doc/templates/sphinx/conf.in.py
master_doc = 'index'
pygments_style = 'sphinx'
html_theme = "mytheme"
extensions = ["custom.extension"]
# in doc/templates/doxygen/Doxyfile.in
HTML_HEADER = header.html
HTML_FOOTER = footer.html
HTML_STYLESHEET = doxygen.css
# in doc/doc_proj1/source/conf.in.py
extensions.append("myext")
# in doc/doc_proj2/Doxyfile.in
INPUT = .
The contents of the .in
files will be concatenated together by qidoc build
That is, a conf.py
file will be generated, containing first the contents of
the file in the template project, then the contents of the file in the doc project.
Translating sphinx documentation¶
You can use qidoc
to help you translate your documentation written with
Sphinx
using sphinx-intl
.
See Sphinx documentation about internationalization for more information.
First, edit the qiproject.xml
to let qidoc
know the list of languages
you are going to support. For instance, to support French and Japanese:
<project version="3">
<qidoc name="foo" type="sphinx">
<translate linguas="fr ja" />
</qidoc>
</project>
Then, edit the conf.py
(or conf.in.py
) to set locale_dirs
.
# in conf.py
locale_dirs = ["locale/"]
# in conf.in.py
locale_dirs = ["../source/locale"]
Then, install sphinx-intl
pip install sphinx-intl
Lastly, run qidoc intl-update
to generate the .pot
and .po
files.
qidoc intl-update
You will end up with several .po
files in source/locale/fr/LC_MESSAGES
that you can edit to start translating English strings into French.
You can now build the French documentation by running
qidoc build --language fr
This command will first generate the .mo
files from the .po
files,
then build the documentation.
The build output will be in /path/to/project/build-doc/html/fr
Running a spell checker¶
You can also use qidoc
to check for spelling errors in your documentation
using sphinxcontrib.spelling
Follow the installation guide in: Installing sphinxcontrib.spelling
Then run
qidoc build --spellcheck
You can specify a list of words to ignore in a spelling_wordlist.txt
file
in the source
directory.
Troubleshooting¶
On Mac OSX, if you get [ERROR]: ValueError unknown locale: UTF-8
, simply
set the LC_ALL
environment variable to en_US.utf8
, like so:
LC_ALL=en_US.utf8 qidoc build