-
Notifications
You must be signed in to change notification settings - Fork 369
gendoc
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 {
...
}
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.
Run the /documentation/api-doc/publish.py
script to publish to sourceforge.
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.
- 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
Run make publish
inside /documentation
publish to sourceforge.
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.