README.md

Compiling mdaencore's Documentation

The docs for this project are built with Sphinx. To compile the docs, first ensure the correct environment is installed, as defined in the docs/requirements.yaml

conda env update --file=requirements.yaml

If this is in a separate environment to your main development environment, you will need to reinstall mdaencore, from the parent directory, into this environment. Alternatively, you can update your development environment with the above yaml by providing the name of that development environment, though it's generally a better idea to keep them separate.

conda env update -n dev_env --file=requirements.yaml

Once the documentation tools and mdaencore are installed, you can use the Makefile in this directory to compile static HTML pages by

make html

The compiled docs will be in the _build directory and can be viewed by opening index.html (which may itself be inside a directory called html/ depending on what version of Sphinx is installed).

A configuration file for Read The Docs (readthedocs.yaml) is included in the top level of the repository. To use Read the Docs to host your documentation, go to https://readthedocs.org/ and connect this repository. You may need to change your default branch to main under Advanced Settings for the project.

If you would like to use Read The Docs with autodoc (included automatically) and your package has dependencies, you will need to include those dependencies in your documentation yaml file (docs/requirements.yaml).