gendoc

How to generate documentation?

Doxygen C++

Write

Use the standard doxygen features to annotate header files. Use one of the following paradigms:

/// Brief description.
void myfun()

/** \brief Brief description.
*   Detailed description.
*/
void myfun()

Latex formulas: \\f$a+b\\f$ or \\f[multiline expression\\f]

Referencing arguments is done as such:

/*! \fn int close(int fd)
\brief Closes the file descriptor \a fd.

To state a c++ primitive, usse \c, e.g. this needs an \c int.

To avoid duplication of documentation, try to use copydoc where possible:

/** \defgroup MyBaseClass_
Here is some important remarks
*/

/**
* MyBaseClass does something useful.
* @copydoc MyBaseClass_
*/
class MyBaseClass {
...
}


/**
* MyDerivedClass is a fancy version of MyBaseClass
* @copydoc MyBaseClass_
*/
class MyDerivedClass : public MyBaseClass {
...
}

Make

Running make doc in the build directory will create documentation. All results will be placed in /doc:

• html contains the html output
• latex contains helper files to interpret latex formulas
• XML contains the documentation in a parseable format

(Optional) You can generate the header information for options (see #108) by issuing: python extra/generate_options_doc.py inside /documentation/api-doc. This will only run after Doxygen has already made a first pass. After this, Doxygen will need another pass.

(Optional) You can generate the in-documentation-examples after setup by issuing: make inside /documentation/examples and python extra/fetch_examples_pdf.py inside /documentation/api-doc to put the example pdfs inside the documentation directories. This does not require Doxygen to already have made a first pass. After this, Doxygen will need another pass.

Publish

Run the /documentation/api-doc/publish.py script to publish to sourceforge.

Python

Write

There are several methods:

• docstrings can be read in from Doxygen.
• docstrings can be added in the swig files (%feature("docstring")).
• Changing the Sphynx index file /doc/sphinx/index.rst In any case, change the index file to add new classes/functions.

Make

• Ensure you have made the Doxygen documentation first.
• Generate /swig/doc.i from doxygen XML output with the help of /documentation/extra/doc2swig.sh
• Do a make rebuild-cache in the builddir.
• Do a make python in the builddir.
• Do a make html in the /doc/sphinx.
• Output is found in /doc/sphinx/_build/html

Publish

Run make publish inside /documentation publish to sourceforge.

Latex

There is a helper package available to have code snippets in your latex document that actually compile (and thus can be unittested) and run, so that output can be transcluded.

To insert a code snippet, do:

\usepackage{pytex}

\begin{pytexTemplate}{main}
from casadi import *
\end{pytexTemplate}

\pytexStart{main}

\begin{pytex}
print ssym("x",2,3)
\end{pytex}

This must go in the preamble:

\usepackage{pytex}

This command groups common code into a template called main:

\begin{pytexTemplate}{main}
from casadi import *
\end{pytexTemplate}

This command starts a new python script file

\pytexStart{main}

This commands adds content to the latest opened python script file, and transcludes result if available

\begin{pytex}
print ssym("x",2,3)
\end{pytex}

To make results available for transclusion, python pytex.py must be run inbetween two pdflatex calls.