diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..ba80efba --- /dev/null +++ b/docs/README.md @@ -0,0 +1,8 @@ +# Sphinx Documentation +This directory contains the files used to generate the [Sphinx documentation site for WecOptTool](https://sandialabs.github.io/WecOptTool/). + +* `build_docs.py` is a script used to run the Sphinx build itself. This script uses the built-in Sphinx API (i.e. the `Sphinx` class and `Sphinx.build()`) rather than Makefiles, which runs counter to the general Sphinx documentation. This is so the Sphinx build process cooperates better with Windows and GitHub Actions, see [#204](https://github.com/sandialabs/WecOptTool/pull/204). This script can be called with either `python build_docs.py --build production` or `python build_docs.py --build debug` options. `--build debug` is best for testing a documentation build locally, and will only build for the Git branch you are currently on. `--build production` is used in the GitHub CI workflows, and generates documentation for all the branches specified in `versions.yaml`. +* The `source/` subdirectory includes `conf.py` (the Sphinx configuration file for the Sphinx build) and all the files populating the documentation site. +* `clean_docs.py` removes the files and directories automatically generated by Sphinx during a build. This should be run before committing changes in this directory to GitHub. +* `versions.yaml` specifies which branches to build the documentation from when the `production` build option is selected when `build_docs.py` is called. This is currently set so `main` is the default landing page (aka `latest`) with `dev` also being built. + \ No newline at end of file