7.3. Building this documentation locally¶
This document describes how to build the OpenFAST documentation on your local machine. Documentation is automatically built and updated on readthedocs when new material is pushed to the github repo. However, while developing documentation, one should build locally to see changes quickly, and without the need to push your changes to see them on readthedocs.
The documentation is based on the use of Doxygen, Sphinx, and Doxylink. Therefore users will need to install these tools as well as several extensions of Sphinx that are utilized.
7.3.1. Install the Tools¶
Install CMake, Doxygen, Sphinx, Doxylink, and the
extensions used. Doxygen uses the dot
application
installed with GraphViz. Sphinx uses a combination
of extensions installed with pip install
as well as some
that come with OpenFAST located in the _extensions
directory. Using Homebrew on Mac OS X,
this would look something like:
brew install cmake
brew install python
brew install doxygen
brew install graphviz
pip install sphinx
pip install sphinxcontrib-doxylink
pip install sphinxcontrib-bibtex
pip install sphinx_rtd_theme
7.3.2. Run CMake Configure and Make the Docs¶
In the OpenFAST repository checkout, if it has not been created yet,
create a build
directory. Change
to the build directory and run CMake with BUILD_DOCUMENTATION
on. If all
of the main tools are found successfully, CMake should configure with the
ability to build the documentation. If Sphinx or Doxygen aren’t found, the
configure will skip the documentation.
Issue the command make docs
which should first build the Doxygen
documentation and then the Sphinx documentation. If this completes
successfully, the entry point to the documentation should be in
build/docs/html/index.html
.
For example, from the OpenFAST directory:
mkdir build
cd build
cmake -DBUILD_DOCUMENTATION:BOOL=ON ..
make docs
If you modify document source files in OpenFAST/docs/source
, you can simply update the html files through another make docs
in OpenFAST/build
:
make docs
7.3.3. Documentation Output¶
After building the documentation, it can be access by opening the output in a browser.
Open the high level html file generated at openfast/build/docs/html/index.html
and begin using the page as any other web page.
7.3.4. Additional Build Targets¶
The html portion of the documentation can be built with make sphinx-html
, and
the output is available at openfast/build/docs/html/index.html
.
If LaTeX is installed, a pdf version of the documentation can be built with
make sphinx-pdf
, and the output is available at openfast/build/docs/latex/Openfast.pdf
.