Writing Dakota Documentation
Install Sphinx and Packages
pip install --user -U Sphinx pip install --user -U myst-parser pip install --user -U sphinx-rtd-theme pip install --user -U sphinxcontrib-bibtex
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, e.g., specifying the Boolean ENABLE_DAKOTA_DOCS 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 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 content (will be built automatically by the dependent targets) make docs-keywords # 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 # Remove output dir user-html 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 setup 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 <dakota build>/docs/user-html/
Note that historical targets for building User’s, and Theory manuals remain in inactive and are activate with DAKOTA_DOCS_LEGACY, but not Reference, since they are (1) broken and (2) subsumed by the new process.
Development Process Notes:
When iteratively editing, if you edit a file in the keywords/ directory it should make the docs-keywords (and therefore docs-sphinx) target out of date.
If you add a new keywords/ file you likely need to touch <dakota source>/docs/CMakeLists.txt to force a rescan of files
You may need to force remove the sphinx output tree <dakota build>/docs/user-html/ to force a rebuild
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\briadam\AppData\Roaming\Python\Python310\Scripts;%PATH% cmake -D DAKOTA_DOCS_DEV:BOOL=FALSE -D JAVA_HOME:PATH="C:\Program Files\Eclipse Adoptium\jdk-18.104.22.168-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)
Important: Note that if you are hunting down documentation errors by line number, the line numbers displayed in Sphinx build warnings/errors allude to the fully-built keyword RST pages, NOT the RST snippet files in docs/keywords. However, the original snippet files will be where you want to ultimately make the correction.
Legacy: Convert LaTeX to RST through Pandoc
pandoc -f latex -t rst Users_Preface.tex -o Users_Preface.rst