mirror of
https://gitlab.kitware.com/vtk/vtk-m
synced 2024-10-05 09:59:12 +00:00
279 lines
9.8 KiB
Markdown
279 lines
9.8 KiB
Markdown
|
# VTK-m User's Guide Source
|
||
|
|
||
|
This directory contains the source for building the VTK-m User's Guide. The
|
||
|
document is written for the [Sphinx](https://www.sphinx-doc.org/en/master/)
|
||
|
document generator.
|
||
|
|
||
|
|
||
|
## Building the documentation
|
||
|
|
||
|
To build the document, you will need the following installed on your
|
||
|
system.
|
||
|
|
||
|
* [Doxygen] - Processes source code to pull out documentation.
|
||
|
* [Sphinx] - Processes [reStructuredText] to build HTML and LaTeX
|
||
|
formatted documents.
|
||
|
* [RTD Theme] - We use the Sphinx Read the Docs theme for formatting the
|
||
|
generated HTML. The build will fail without this installed.
|
||
|
* [Sphinx CMake Domain] Sphinx does not support documenting CMake
|
||
|
elements out of the box. This extension provides that support.
|
||
|
* [Breathe] - Forms a bridge betweein Doxygen and Sphinx to allow the
|
||
|
Sphinx reStructuredTest to include documentation extracted by Doxygen.
|
||
|
|
||
|
To enable document generation, you first must turn on the CMake option
|
||
|
`VTKm_ENABLE_DOCUMENTATION`, which turns on the Doxygen documentation. With
|
||
|
that on, you can then turn on the `VTKm_ENABLE_USERS_GUIDE` CMake option.
|
||
|
|
||
|
The documentation will be built into HTML format in the
|
||
|
`docs/users-guide/html` directory in the build. It will also build LaTeX
|
||
|
files in `docs/users-guide/latex`. It will come with a `Makefile` that can
|
||
|
be used to generate a pdf form (given the proper LaTeX compiler).
|
||
|
|
||
|
|
||
|
## Features of the documents
|
||
|
|
||
|
The VTK-m User's Guide is built as a standard [Sphinx] project. However,
|
||
|
there are some features that writers should be aware of.
|
||
|
|
||
|
### Writing credit
|
||
|
|
||
|
Kenneth Moreland is the main author of this document. If you have made a
|
||
|
contribution, you can credit yourself in the `Contributors` section of
|
||
|
[acknowledgements.rst].
|
||
|
|
||
|
### Provided substitutions
|
||
|
|
||
|
The Sphinx configuration provides some convenient substitutions that can be
|
||
|
used throughout the document.
|
||
|
|
||
|
* `|VTKm|` This should be used whenever `VTK-m` is referenced. The
|
||
|
substitution contains formatting for the word.
|
||
|
|
||
|
### Expanded directives
|
||
|
|
||
|
This reStructuredText is build with some extended directives.
|
||
|
|
||
|
#### Info boxes
|
||
|
|
||
|
Two new "admonition" boxes are supported: `didyouknow` and `commonerrors`.
|
||
|
It is encouraged to use these boxes to highlight interesting features or
|
||
|
common gotchas. These are use like other tip boxes.
|
||
|
|
||
|
``` restructuredtext
|
||
|
.. didyouknow::
|
||
|
In this guide we periodically use these **Did you know?** boxes to
|
||
|
provide additional information related to the topic at hand.
|
||
|
|
||
|
.. commonerrors::
|
||
|
**Common Errors** blocks are used to highlight some of the common
|
||
|
problems or complications you might encounter when dealing with the
|
||
|
topic of discussion.
|
||
|
```
|
||
|
|
||
|
### Section references
|
||
|
|
||
|
It is desired for the VTK-m User's Guide to be available both online as web
|
||
|
pages and as a self-contained document (e.g. pdf). One issue is that
|
||
|
traditional paper documents work best with numbered references to parts,
|
||
|
chapters, and sections whereas html documents prefer descriptive links.
|
||
|
|
||
|
To service both, this document has extensions to automatically provide
|
||
|
references to document parts. Three roles are created: `:partref:`,
|
||
|
`:chapref:`, and `:secref:` to create cross references to parts, chapters,
|
||
|
and sections, respectively. They each take a label, and Sphinx is
|
||
|
configured with numfig and autosection labels. These labels take the form
|
||
|
<file>:<title> where <file> is the name of the file containing the section
|
||
|
(without the `.rst` extension) and <title> is the full name of the section.
|
||
|
|
||
|
Here are examples of cross references.
|
||
|
|
||
|
``` restructuredtext
|
||
|
:partref:`part-getting-started:Getting Started`
|
||
|
|
||
|
:chapref:`introduction:Introduction`
|
||
|
|
||
|
:secref:`introduction:How to Use This Guide`
|
||
|
```
|
||
|
|
||
|
### Example code
|
||
|
|
||
|
The VTK-m User's Guide has numerous code examples. These code examples are
|
||
|
pulled from source files that are compiled and run as part of VTK-m's
|
||
|
regression tests. Although these "tests" are not meant to be thorough
|
||
|
regression tests like the others, they ensure that the documentation stays
|
||
|
up to date and correct.
|
||
|
|
||
|
Examples are added to the `examples` directory more or less like any other
|
||
|
unit test in VTK-m (except by convention we start the name with
|
||
|
`GuideExample`). Each of these files can then be scanned to find excerpts
|
||
|
to include as an example in the guide.
|
||
|
|
||
|
#### Marking examples in the code
|
||
|
|
||
|
A simple text scanner goes through the example code looking for lines
|
||
|
containing a comment starting with 4 slashes, `////`. Any such line will
|
||
|
not be included in the example.
|
||
|
|
||
|
An example can be started with `//// BEGIN-EXAMPLE` and ended with
|
||
|
`//// END-EXAMPLE`. Each of these must be given the name of the example.
|
||
|
|
||
|
``` cpp
|
||
|
////
|
||
|
//// BEGIN-EXAMPLE EquilateralTriangle
|
||
|
////
|
||
|
vtkm::Vec<vtkm::Vec2f_32, 3> equilateralTriangle = { { 0.0f, 0.0f },
|
||
|
{ 1.0f, 0.0f },
|
||
|
{ 0.5f, 0.8660254f } };
|
||
|
////
|
||
|
//// END-EXAMPLE EquilateralTriangle
|
||
|
////
|
||
|
```
|
||
|
|
||
|
#### Loading examples in the documentation
|
||
|
|
||
|
An example can be loaded into the VTK-m User's Guide using the extended
|
||
|
reStructuredText `load-example` directive. The directive takes the name of
|
||
|
the example as its argument. `load-example` should also be given the
|
||
|
`:file:` and `:caption:` options.
|
||
|
|
||
|
``` restructuredtext
|
||
|
.. load-example:: EquilateralTriangle
|
||
|
:file: GuideExampleCoreDataTypes.cxx
|
||
|
:caption: Defining a triangle in the plane.
|
||
|
```
|
||
|
|
||
|
The following options are supported.
|
||
|
|
||
|
* `:file:` The filename of the file containing the named example. The
|
||
|
filename is relative to the `examples` directory.
|
||
|
* `:caption:` The caption used for the example.
|
||
|
* `:nolinenos:` Turn off line numbering. By default, line numbers are
|
||
|
shown, but they are suppressed with this option.
|
||
|
|
||
|
#### Referencing examples
|
||
|
|
||
|
The example is registered as a `code-block` the named registered as the
|
||
|
example named prepended with `ex:`. This name can then be referenced with
|
||
|
the `:ref:` and `:numref:` roles as with figures, sections, and other cross
|
||
|
references.
|
||
|
|
||
|
The `:numref:` role is particularly useful for referencing each example.
|
||
|
Using `:numref:` with just the name will be replaced with a link titled
|
||
|
"Example #" with "#" being the number of the example.
|
||
|
|
||
|
``` restructuredtext
|
||
|
:numref:`ex:EquilateralTriangle` shows how the :class:`Vec` class can be used to
|
||
|
store several points in the same structure.
|
||
|
```
|
||
|
|
||
|
The `:numref:` role also supports custom text with number substitution as
|
||
|
described in the [Sphinx
|
||
|
documentation](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-numref)
|
||
|
|
||
|
``` restructuredtext
|
||
|
:numref:`Example %s representes an equilateral triangle<ex:EquilateralTriangle>`
|
||
|
using the :class:`Vec` class.
|
||
|
```
|
||
|
|
||
|
#### Pausing and resuming capture
|
||
|
|
||
|
Sometimes it is useful to insert code in the compiled test that is not
|
||
|
included as part of the example. This is useful to, for example, insert a
|
||
|
check for values, which can verify that the code is working correctly but
|
||
|
is not necessary for the example.
|
||
|
|
||
|
When a `//// PAUSE-EXAMPLE` is inserted into the code, the following lines
|
||
|
will not be captured until the line `//// RESUME-EXAMPLE` is encountered.
|
||
|
|
||
|
``` cpp
|
||
|
range.Include(2.0); // range is now [0.5 .. 2]
|
||
|
bool b5 = range.Contains(0.5); // b3 is true
|
||
|
bool b6 = range.Contains(0.6); // b4 is true
|
||
|
|
||
|
range.Include(vtkm::Range(-1, 1)); // range is now [-1 .. 2]
|
||
|
//// PAUSE-EXAMPLE
|
||
|
VTKM_TEST_ASSERT(test_equal(range, vtkm::Range(-1, 2)), "Bad range");
|
||
|
//// RESUME-EXAMPLE
|
||
|
```
|
||
|
|
||
|
#### Referencing a specific line
|
||
|
|
||
|
You apply a label to a specific line in the code by adding a `//// LABEL`
|
||
|
comment right before it. The `LABEL` needs a text string used to reference
|
||
|
the line.
|
||
|
|
||
|
``` cpp
|
||
|
////
|
||
|
//// BEGIN-EXAMPLE VecCExample
|
||
|
////
|
||
|
//// LABEL index-to-ijk
|
||
|
VTKM_EXEC vtkm::VecCConst<vtkm::IdComponent> HexagonIndexToIJK(vtkm::IdComponent index)
|
||
|
{
|
||
|
static const vtkm::IdComponent HexagonIndexToIJKTable[8][3] = {
|
||
|
{ 0, 0, 0 }, { 1, 0, 0 }, { 1, 1, 0 }, { 0, 1, 0 },
|
||
|
{ 0, 0, 1 }, { 1, 0, 1 }, { 1, 1, 1 }, { 0, 1, 1 }
|
||
|
};
|
||
|
|
||
|
return vtkm::make_VecC(HexagonIndexToIJKTable[index], 3);
|
||
|
}
|
||
|
|
||
|
//// LABEL ijk-to-index
|
||
|
VTKM_EXEC vtkm::IdComponent HexagonIJKToIndex(vtkm::VecCConst<vtkm::IdComponent> ijk)
|
||
|
{
|
||
|
static const vtkm::IdComponent HexagonIJKToIndexTable[2][2][2] = {
|
||
|
{
|
||
|
// i=0
|
||
|
{ 0, 4 }, // j=0
|
||
|
{ 3, 7 }, // j=1
|
||
|
},
|
||
|
{
|
||
|
// i=1
|
||
|
{ 1, 5 }, // j=0
|
||
|
{ 2, 6 }, // j=1
|
||
|
}
|
||
|
};
|
||
|
|
||
|
return HexagonIJKToIndexTable[ijk[0]][ijk[1]][ijk[2]];
|
||
|
}
|
||
|
////
|
||
|
//// END-EXAMPLE VecCExample
|
||
|
////
|
||
|
```
|
||
|
|
||
|
This line can be referenced in the text using the extended reStructuredText
|
||
|
`:exlineref:` role. The role takes references of the form
|
||
|
"example-name:line-label". If given just this reference, the link text is
|
||
|
"Example #, line #".
|
||
|
|
||
|
``` restructuredtext
|
||
|
A function to convert a 3D index to a flat index starts on
|
||
|
:exlineref:`VecCExample:ijk-to-index`.
|
||
|
```
|
||
|
|
||
|
`:exlineref:` also accepts a formatting string like the `:numref:` builtin
|
||
|
role. `%s` and `{line}` will be replaced with the line number.
|
||
|
`:exlineref:` also follows the [`:numref:`
|
||
|
convention](https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-numref)
|
||
|
of replacing `{number}` and `{name}` with the example number and caption,
|
||
|
respectively.
|
||
|
|
||
|
``` restructuredtext
|
||
|
You can convert a flat index to a 3D index (shown starting on
|
||
|
:exlineref:`line {line} in Example {number}<VecCExample:index-to-ijk>`) and
|
||
|
the inverse function (:exlineref:`line %s<VecCExample:ijk-to-index>`).
|
||
|
```
|
||
|
|
||
|
### Ingesting Doxygen
|
||
|
|
||
|
The VTK-m User's Guide is built with [Breathe], which allows it to pull in
|
||
|
Doxygen documentation. Use [Breathe's
|
||
|
directives](https://breathe.readthedocs.io/en/latest/directives.html#directives)
|
||
|
to include the doxygen documentation.
|
||
|
|
||
|
[Sphinx]: https://www.sphinx-doc.org/en/master/
|
||
|
[Doxygen]: https://www.doxygen.nl/
|
||
|
[RTD Theme]: https://sphinx-themes.org/sample-sites/sphinx-rtd-theme/
|
||
|
[Sphinx CMake Domain]: https://github.com/scikit-build/moderncmakedomain
|
||
|
[Breathe]: https://www.breathe-doc.org/
|
||
|
[reStructuredText]: https://docutils.sourceforge.io/rst.html
|