310579b9a7
Some common VTK-m options such as the device and log level could be specified on the command line but not through environment variables. It is not always possible to set VTK-m command line options, so environment variables are added. Also added documentation to the user's guide about what options are available and how to set them. |
||
|---|---|---|
| .. | ||
| _ext | ||
| examples | ||
| images | ||
| acknowledgements.rst | ||
| advanced-types.rst | ||
| base-types.rst | ||
| basic-array-handles.rst | ||
| basic-filter-impl.rst | ||
| building.rst | ||
| CMakeLists.txt | ||
| color-table-presets.rst | ||
| conf.py | ||
| dataset.rst | ||
| error-handling.rst | ||
| extended-filter-impl.rst | ||
| fancy-array-handles.rst | ||
| general-approach.rst | ||
| genindex.rst | ||
| implicit-functions.rst | ||
| index.rst | ||
| initialization.rst | ||
| introduction.rst | ||
| io.rst | ||
| license.rst | ||
| logging.rst | ||
| managing-devices.rst | ||
| math.rst | ||
| memory-layout.rst | ||
| part-advanced.rst | ||
| part-appendix.rst | ||
| part-core.rst | ||
| part-developing.rst | ||
| part-getting-started.rst | ||
| part-using.rst | ||
| provided-filters.rst | ||
| quick-start.rst | ||
| README.md | ||
| rendering.rst | ||
| requirements.in | ||
| requirements.txt | ||
| running-filters.rst | ||
| simple-worklets.rst | ||
| timer.rst | ||
| unknown-array-handle.rst | ||
| version.rst | ||
| vtkm.module | ||
| working-with-cells.rst | ||
| worklet-error-handling.rst | ||
| worklet-types.rst | ||
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-mis 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
: