jgillis edited this page Apr 18, 2014 · 24 revisions

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.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.