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