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.

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
« previous | up | next »