# qiBuild documentation

# 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

- Building documentation with qidoc
  - Configuring qidoc
  - Building documentation
  - Browsing the documentation
  - Adding templates
  - Translating sphinx documentation
  - Running a spell checker
  - Troubleshooting

## 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

Changelog CMake index Python index Index