Manual Documentation Build

During development and testing, it’s often necessary to build CSXCAD and openEMS documentation manually.

If you are an end-user, please view CSXCAD and openEMS’s development documentation via https://openems.readthedocs.org, and view the stable documentation via https://docs.openEMS.de. There’s no need to manually build documentation for end users.

Tip

The following instructions are working as the time of writing, but it can become outdated. If you have difficulties building the project from source, refer to these official CI/CD test scripts in the source code.

Install Project Dependencies

It’s only possible on build project documentation after CSXCAD and openEMS has already been installed.

Before proceeding…

  1. Refer to Requirements for a list of dependencies, including GNU Octave and Python.

  2. Refer to Clone, Build and Install and Install Python Extensions Automatically to install CSXCAD, openEMS, and Python extensions automatically.

  3. Alternatively, refer to Manual C++ Build and Install and Install Python Extensions Manually to install CSXCAD, openEMS, and Python extensions manually.

Important

GNU Octave and all Python extensions must also be installed.

Activate Python venv

By default, Python extensions and their dependencies are installed into an isolated “virtual environment” in the venv subdirectory of openEMS’s installation path. If openEMS is installed to ~/opt/openEMS, the Python venv exists in ~/opt/openEMS/venv.

This environment must be activated before building documentation for CSXCAD and openEMS.

source ~/opt/openEMS/venv/bin/activate

Install Documentation-Specific Dependencies

Documentation is available in the doc-src subdirectory of openEMS-Project.git:

cd openEMS-Project/doc-src

# install documentation-specific dependencies
pip3 install -r requirements.txt

Build Documentation

One builds the documentation via Python Sphinx.

cd openEMS-Project/doc-src

# build documentation
make html

Documentation Locations

  • Documentation Homepage: Most pages are located within openEMS-Project/doc-src.

    • Submit Pull Requests directly against openEMS-Project.git.

  • API Documentation: It’s located within openEMS-Project/CSXCAD/matlab and openEMS-Project/openEMS/matlab.

    • A custom script openEMS-Project/doc-src/octave/generate_octave_docs.py is used to is used to extract Octave docstrings as Markdown documentation (not restructuredText).

    • The Python documentation is generated from Python docstrings natively by Sphinx.

    • Submit Pull Requests against CSXCAD.git and openEMS.git.

  • Examples and Tutorials: This is the most underdeveloped section of the documentation. Currently, only a few Python tutorials are available, which are automatically generated from the Python example source code from openEMS-Project/openEMS/python/Tutorials/.

    • Submit Python examples to openEMS.git, which is automatically converted to an “article” by extracting Python comments and interleaving them with Python code.

    • The author of this documentation page believes that the auto-generation has serious limitations. Article-format tutorials are seriously in need (or at least, this auto-generator needs serious upgrade to become a full-featured “literate programming” system). But a plan has not yet been worked out.