qidoc3

General

  • usable without templates repo

  • generate everything in <project>/build-doc: no longer required to mess with .gitignore

  • add a html prefix everywhere (<project>/build-doc/html), This is useful to build man pages in build-doc/man, and doxygen creates the prefix anyway.

  • Force Doxyfile to use GENERATE_LATEX=YES and GENERATE_HTML=YES

  • 3 steps: configure, build, install

  • Can choose any doc to be the root (now more dest="." in the qiproject.xml) => install only one doc, and it’s this one that becomes the root

  • FIXME: Things that are just tools (CMake domain, NAOQi event domains, doxylink, qiapidoc): how do we find it? Currently we hack sys.path in our conf.py or conf.in.py file, and it’s tedious.

    Python WorkTree + virtualenv seems the way to go long-term.

Standalone Doxygen

<worktree>
|_ libfoo
    |__ qiproject.xml
    |__ Doxyfile
    |__ foo
    |    |__ foo.h
    |__ dox
         |__ foo.dox
         |__ Doxyfile
         |__ qiproject.xml

Here what the files would look like

<!-- libfoo/qiproject.xml -->

<project version="3" >
  <qidoc name="libfoo-dox" type="doxygen" />
</project>

# libfoo/Doxyfile

INPUT = foo/ dox/
OUTPUT_DIRECTORY = build-doc
EXAMPLE_PATH = ...
  • INPUT is parsed and rewritten when the Doxyfile is generated in build-doc
  • OUTPUT_DIRECTORY is always re-set to <build-doc>
  • We also force GENERATE_LATEX=NO and GENERATE_HTML=YES. Since everything happens in <build-doc> and is correctly prefixed, it does not matter. Also, always generating the XML is not that costly, even if it’s currently only used by qiapidoc
  • For the same reason, we alwas set GENERATE_TAGFILE, even if the doxyfile is standalone

Standalone Sphinx

<worktree>
|__ libfoo
    |__ qiproject.xml
    |__ doc
        |__ source
            |__ conf.py
<!-- libfoo/qiproject.xml -->

<project version="3">
  <project src="doc" />
</project>

<!-- libfoo/doc/qiproject.xml -->

<project version="3">
  <qidoc name="libfoo-doc" type="sphinx" />
</project>

# libfoo/doc/source/conf.py

man_pages = [
    ('man/qisrc', 'qisrc', u'Handle several project sources',
    [u'Aldebaran Robotics'], 1),
]

The file is just generated in libfoo/doc/build-doc, and there is no need to changes the relative file paths

This works just fine

cp source/conf.py build-doc/conf.py
sphinx-build -c build-doc -b man source  build-doc

With templates

  • You have to be explicitly using the templates by using conf.in.py and Doxyfile.in instead of conf.py and Doxyfile.
  • In this case, a template is fetched from the “templates repo” and configured in build-doc, and then we just append the .in

With deps

FIXME: Current syntax is

<project version="3">
  <qidoc name="a">
    <depends name="b" />
    <depends name="c" />
  <qidoc>
</project>

This is not consistent with the depends tag used in qibuild:

<project version="3">
  <qibuild name="a">
    <depends runtime="true" buildtime="true" names="b c" />
  <qibuild>
</project>

Doxygen -> Doxygen

Let’s say hello doxygen documentation depends on world doxygen documentation

  • The Doxyfile generated in build-doc/html is patched to look like:
GENERATE_TAGFILE       = <build-doc>/doxytags/hello.tag
TAGFILES               = <build-doc>/doxytags/world.tag=<relpath>

Where <relpath> is the relative path of world when hello is built, usually ../world

Sphinx -> Doxygen (with qiapidoc)

Let’s say hello sphinx documentation depends on world doxygen documentation, and you want to use qiapidoc

qiapidoc requires a qiapidoc_srcs which is the path to the XML file generated by world Doxyfile. Since we force GENERATE_HTML to YES it’s easy to generate the correct Python setting.

qiapidoc_srcs = '<world>/build-doc/xml/'

Note that there can be only one dependency, hence the following syntax:

<project version="3">
  <qidoc name="hello" type="sphinx">
    <qiapidoc doxydoc="hello" />
  </qidoc>
</project>

Sphinx -> Sphinx

Let’s say hello sphinx documentation depends on world sphinx documentation.

We won’t try to use intersphinx, which is broken anyway.

Instead, we have a qido-ref directive, which behaves correctly depending on whether we are hosted or not. (see below)

Version numbers

You can hard-code the version number in the conf.py (Useful for qibuild)

If you use a template, the version number will be configured for you.

Build type

3 build types:

  • hosted : we assume there is a web server hosting the documentation:

    we can use things like /static/js. We hide the sources and the warnings

  • internal : same as hosted, except we show the sources and the warnings

  • local : every link to an external doc in a full http:// URL, not just a relative path

This as an impact on both the implementation of the qidoc-ref directive, and on the templates.

Building and installing

When building: configure everything with absolute paths (easier)

When installing: re-configure everything with relative paths before installing

Examples

If there is just one file, sphinx and doxygen can handle that just fine

The problem appears when there is more than one file.

Convention: one directory per example

We want two things:

  • Generate a zip with the sources of the examples
  • Copy the source of the examples in an ‘examples’ directory when we build the doc

Syntax:

foo-doc
|__ source
|   |__ index.rst
|__ samples
    |__ a
    |   |__ CMakeLists.txt
    |   |__ a.cpp
    |__ b
       |__ CMakeLists.txt
       |__ b.cpp
<!-- top qiproject.xml -->

<project version="3" />

  <qidoc name="foo" type="sphinx" />
    <examples>
      <example src="samples/a" />
      <example src="samples/b" />
    </examples>
  </qidoc>

</project>

Pre-build command

<project version="3" />

  <qidoc name="foo" type="sphinx" />
    <prebuild cmd="tool/gen_some_rst.py" />
  </qidoc>

</project>
« previous | up | next »