This is a start of moving the VTK-m User's Guide into the VTK-m source. This is only the start of the process. There are several goals of this work. 1. Integrate the documentation into the source code better to better keep the code up to date. 2. Move the documentation over to Sphinx so that it can be posted online and be more easily linked. 3. Incoporate Doxygen into the guide to keep the documentation consistent. 4. Build the user guide examples as part of the VTK-m CI to catch compatibility changes quickly. |
||
---|---|---|
.. | ||
_ext | ||
examples | ||
images | ||
acknowledgements.rst | ||
base-types.rst | ||
building.rst | ||
CMakeLists.txt | ||
conf.py | ||
genindex.rst | ||
index.rst | ||
introduction.rst | ||
license.rst | ||
part-advanced.rst | ||
part-appendix.rst | ||
part-core.rst | ||
part-developing.rst | ||
part-getting-started.rst | ||
part-using.rst | ||
quick-start.rst | ||
README.md | ||
vtkm.module |
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 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 wheneverVTK-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.
.. 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
: