Generating IREP documentation¶
The irep-generate
command described in the build documentation can be used to auto-generate sphinx documentation for WKT headers. You can
include the generated .rst
files in your code’s documentation.
irep-generate --mode rst
¶
To generate .rst
files for WKT headers, run irep-generate --mode
rst
as follows:
$ irep-generate --mode rst wkt_foo.h wkt_bar.h wkt_baz.h
This will generate foo.rst
, bar.rst
, and baz.rst
, and it will
also copy in an irep_types.rst
file that describes IREP data types.
foo.rst
and friends will contain referencs to type descriptions in
this file.
You can see what the generated documentation looks like here:
Doc
macros¶
You can annotate any WKT header with a Doc
macro like this:
ir_int(nx, 1) Doc(( Number of grid cells in 1st dimension ))
If irep-generate
finds a Doc
string in an IREP header, it is
carried into the Description field in tables in the generated IREP
documentation. Doc
strings can be considered free-form RST, so you
can use inline makup to create more complex descriptions. For example, if
you wanted to use the RST ::
construct to include some preformatted
text, you coudl do that like this:
ir_int(nx, 1) Doc((
::
This is a longer descrpition:
- thing one
- thing two
- etc.
))
Basically, the Doc
string is one paragraph of text, and will be
reformatted (nicely) in the HTML output.
Introductions¶
You can have IREP include introductory text in your table definitions. If
you are generating code for wkt_mesh.h
, and irep-generate finds
``mesh/introduction.rst
in the current directory, then it will be
included at the top of the documentation for wkt_mesh.h
.
By default, irep-generate
searches the current directory, but you can
tell it to look else where with --doc-dir <path>
.
Thre is an example introduction.rst
file in the documentation for
IREP itself. See that for an example for how you might set up your own
docs.
Details files¶
If additional details for elements, or groups of elements, are desired,
you can write a details file. These go alongside the
introduction.rst
files described above. If irep-generate
finds a
details file under mesh/
when generating code for wkt_mesh.h
, it
will generate a link to it in the generated documentation.
The naming of the details file follows a simple rule. For example, consider the parameter:
material.opacity.polynomial.absorption.e_pow
The following filenames are searched in order:
mesh/box-xmax.rst
mesh/box.rst
mesh/mesh.rst
That is, the search first looks for the most specific possible file. If
your tables are deeper than our examples, you can keep adding levels
separate by dashes (-
). If one of these names exists, it is linked as
the “details” file for that parameter. If not, the search goes to the
closest surrounding subtable. (So you could give details on all the
parameters in the “absorption” table by making a details file with the
second name in the list above.) And so on. The search ends by looking for
a details file “material.rst”. If none are found, no details link is made
for the element.
As with introduction.rst
, you can use the --doc-dir
parameter to
irep-generate
to tell it where to look.