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.

Clone this wiki locally
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.