Debian Codegraph @

demo/README

raw
1 Documenting DOLFIN demos
2 ========================
3
4 The documentation for the DOLFIN demos is written by hand and located
5 together with the demos in the DOLFIN source tree. To document a (new)
6 DOLFIN demo located in the directory foo (for instance pde/poisson),
7 follow the two steps below. In general, the simplest way is probably
8 to look at one of the documented demos for instance
9 (demo/pde/poisson/) and follow the same setup.
10
11 1) Add these 3 files
12
13 * foo/common.txt -- containing common information such as the main
14 features the demo illustrates and, if applicable, a mathematical
15 description of the differential equation that is solved. This file
16 should then be included in the C++ and Python versions.
17
18 * foo/cpp/documentation.rst -- containing the reST source file with
19 the documentation that is specific to the C++ version of the demo.
20
21 * foo/python/documentation.rst -- containing the reST source file
22 with the documentation that is specific to the Python version of
23 the demo.
24
25 If either the C++ or the Python version of the demo does not exist,
26 feel free to add the version and continue.
27
28 2) Move the directory foo from the directory undocumented/ to the
29 suitable directory (for instance pde/ or la/).
30
31
32 Note
33
34 The demo documentation is automatically included in the complete
35 DOLFIN documentation when running make doc after building
36 DOLFIN. While documenting a demo, it may be handy to only run
37 make doc_demo and then make doc_html_[python|cpp].
38
39 Note
40
41 Tests for the validity of the code snippets used in the demo
42 documentation are included in the standard DOLFIN tests.
43
44 C++ and Python specific contents
45 ================================
46
47 The C++ and Python documentation reST source files should
48
49 * Explain each step of the solution procedure. Do this by including
50 and explaining code snippets from the demo source code.
51
52 * Include links to the API documentation using the :cpp:class: and
53 :py:class: directives. Note that for the Python classes, the
54 full module path is required (for instance
55 py:class:dolfin.cpp.NewtonSolver)
56
57 * Include the complete set of files needed to run the demo using the
58 include directive.