Sphinx build documentation

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.
+