Dakota Documentation Mechanics
Authoring Dakota documentation requires tools described in
Setup Development Environment, notably Python Sphinx, Python/Perl (to extract input
file examples), Java Development Kit (to parse
keyword reference files), and optionally Doxygen and LaTeX (for the
C++ developer manual).
Install Sphinx and Packages
A representative way to install the tools:
pip install --user -U Sphinx pip install --user -U myst-parser pip install --user -U sphinx-rtd-theme pip install --user -U sphinxcontrib-bibtex
You may alternately use
pip3 if targeting Python 3 when both 2
and 3 are installed.
Interactive Documentation Build
Bare Sphinx Build
sphinx-build command will build almost all of the documentation, except for keyword reference pages and sample Dakota input files.
cd <dakota checkout>/docs/user sphinx-build -b html <source dir> <build dir> # to speed up build using all available cores (may suppress some cross reference and other warnings/errors): sphinx-build -b html -j auto <source dir> <build dir>
CMake-based Build on Mac/Linux
This build process is more similar to historical documentation build using the routine CMake-based build process.
Python and the Sphinx Python tools specified above, with the sphinx-build executable on your PATH.
Java JDK 11 or newer. For example on RHEL7 install java-11-openjdk-devel from EPEL and specify JAVA_HOME:PATH=/usr/lib/jvm/java-11 to CMake
Doxygen 1.8.20 or newer (for C++ docs/dev manual)
LaTeX (for PDF output), probably 2015 or newer will do
Perl for generating user manual input samples
Building / Editing
First, configure Dakota with CMake, enabling documentation as usual,
ENABLE_DAKOTA_DOCS:BOOL=TRUE or the typical
developer convenience macros such as
DevDistro. You may need to
help CMake find Java JDK 11 per above. While in theory reference
manual building should work without enabling tests, enabling them via
DAKOTA_ENABLE_TESTS:BOOL=TRUE may be a safer choice.
Then build the docs-sphinx target (or optionally the docs-keywords, then docs-sphinx target, but the dependency is tracked) via IDE or command line, e.g.,
cd <dakota build>/docs # Generate reference or example input file content # (will be built automatically by the dependent targets) make docs-keywords make docs-user-samples # To see the most current make targets: make help # Build the whole sphinx manual in serial make docs-user # Build the whole sphinx manual in parallel much faster but may omit some warnings/errors make docs-user-fast # Only rebuild updated content (may miss some dependencies, but is fast): make docs-user-increm # Remove output dir user-html; useful to force generation of warnings/errors make docs-user-clean # Generate C++ Doxygen developer manual (requires LaTeX) cd <dakota build>/docs/dev make docs-dev-html make docs-dev-pdf
The build is set up to use all available cores to build the docs, so should only take a couple minutes.
The keyword files will get generated directly into the source tree at
<dakota source>/docs/user/usingdakota/reference(for now) while the generated manual will appear in
When iteratively editing, if you edit a metadata file in the
keywords/directory it should make the
docs-keywords(and therefore docs-user*) target out of date.
If you add a new
keywords/metadata file you likely need to touch
<dakota source>/docs/CMakeLists.txtto force a rescan of files
Historical targets for building User’s, and Theory manuals remain in
docs/inactiveand are enabled with
DAKOTA_DOCS_LEGACY. The Reference manual is not, since it’s (1) broken and (2) subsumed by the new Sphinx process.
CMake-based on Windows
You can build the user manual in its entirety on Windows using CMake, though currently Visual Studio is required.
Python + Sphinx
Java 11 JDK
Visual Studio (community edition will work)
Command prompt config example, since I didn’t have sphinx-build on my global PATH. If you do, or you set a variable like https://cmake.org/cmake/help/latest/variable/CMAKE_PROGRAM_PATH.html#variable:CMAKE_PROGRAM_PATH to find it, you can likely do this from the CMake GUI
set PATH=C:\Users\username\AppData\Roaming\Python\Python310\Scripts;%PATH% cmake -D DAKOTA_DOCS_DEV:BOOL=FALSE -D JAVA_HOME:PATH="C:\Program Files\Eclipse Adoptium\jdk-188.8.131.52-hotspot" -D Python_EXECUTABLE=C:\Python310\python.exe ..\source\docs
After which you can open DakotaDocs.sln in Visual Studio and build some or all of the projects.
Alternately, from command line in the build dir:
cmake --build . --target docs-user-samples
Keyword Reference Pages
The following section only applies if you are building all the documentation without CMake. The existing CMake build process will handle keyword reference page generation automatically.
Fully-fleshed-out keyword reference pages are not checked in under with the rest of the documentation files in the
docs/user folder. The keyword documentation
contents are stored in the
docs/keywords folder. In this folder, each file contains RST snippets, with custom Dakota markdown that demarcates the sections in
each file. These files need to be built into full RST pages before being added to the larger Sphinx manual. To add these keyword reference pages to the Sphinx build,
you must perform the following additional steps:
Acquire a Java IDE (such as Eclipse or IntelliJ). The next step will be much easier for you if you get an IDE to manage your Java classpath for you.
Run the RefManGenerator application in the java_utils project, using “<dakota checkout>/docs/keywords” as the first argument and an empty output folder as the second argument.
After RefManGenerator finishes running, copy all the output from your output folder to “<dakota checkout>/docs/user/usingdakota/reference” folder
Run the build commands in the “Bare Sphinx Build” section. Make sure that build detects all the keyword pages that you copied (i.e. it should take longer to build)
Legacy: Convert LaTeX to RST through Pandoc
pandoc -f latex -t rst Users_Preface.tex -o Users_Preface.rst