Run Sphinx local

In the bim2sim project Sphinx is used to generate the documentation. The documentation is generate via the CI. But to extend or adapt the documentation it is very useful to run the documentation generation locally. Following it is shown how to do that.

First install the following python packages based on the pyproject.toml. Therefore you need to switch into the root directory of the bim2sim repo, which includes the project.toml file.

  cd [bim2sim-Root]/bim2sim/
  pip install -e '.[docu]'

After that, switch in to the docs folder of the bim2sim repo.

cd bim2sim-Root/bim2sim/docs

Next, regenerate the description of the python code (classes/functions) For bim2sim itself:

sphinx-apidoc -M -o source/code ../bim2sim

And for documentation utilizes:

sphinx-apidoc -M -o source/code utilities

Next, delete the existing html-files (needed to prevent strange behaviour)

make clean

Next, generate fresh html-files

make html

Now, the html based documentation is available. Switch into the folder and open the file index.html.

cd build/html

Don’t run the command “sphinx-quickstart”, because this command overwrites the configuration of the bim2sim documentation.

Troubleshooting

Warning: import failures - No module named XXXX

Please install the dependencies for all plugins. (see TEASER, EnergyPlus, LCA, AixLib and HKESim)

Problems with code documentation

If there are problems regarding the generated code documentation. Please delete the folder ../source/code (in docs folder) and regenerate the code documentation (see above).

rm -r source/code