indocumentationexamples

Joris Gillis edited this page Jun 17, 2011 · 12 revisions

We refer to in-documentation-examples as code files that:

  • are small
  • demonstrate one or a few methods, but may do so in-depth
  • may produce graphs and helpful output
  • do not aim to solve any academic or industrial problem
  • are to be included in the API-docs

The location of these examples is /documentation/examples. You can add python file .py, C++ files .cc or octave files .m in an arbitrary sub-directory. Each example (even the python ones) should be accompanied by a header file with the same name.

The structure of the header file for python examples is as follows:

/** 
* A long description
*
* <a href="{relative path + basename}.pdf">View output (PDF)</a>
*
* \example {relative path + basename}.py
*
* \sa
* \code
* {Classes or methods that should get a link to this example. Use full namespace}
* \endcode
*
*/
}}} 

When issuing a {{{make}}} command in {{{/documentation/examples}}}, python examples will be converted to pdf (pyreport) and C++ examples to txt (stdout).

These outputs can be included in the API-documentation by issuing:

{{{python fetch_examples_pdf.py }}} in {{{/documentation/api-doc}}}

See [wiki:indocumentationexamplessetup] for further instructions on compiling these examples.
See [wiki:gendoc] for further instructions on compiling documentation.

in-documentation-examples can be run in the [wiki:unittests] suite.