From a8e4e319f91215c1e11f4808e22ceca9b01ea92f Mon Sep 17 00:00:00 2001 From: michaelcdevin Date: Sun, 12 Jan 2025 16:00:07 -0700 Subject: [PATCH 1/3] added README to docs folder to explain Sphinx build process --- docs/README.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 00000000..8ef05ee7 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,6 @@ +# 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. 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 the `main` and `dev` branches. +* 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. From fa02b71ee548e997f41b8c48292a44e0b11ddbfa Mon Sep 17 00:00:00 2001 From: michaelcdevin Date: Sun, 12 Jan 2025 16:03:11 -0700 Subject: [PATCH 2/3] updated README with build versions explanation --- docs/README.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 8ef05ee7..5d547d16 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +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. 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 the `main` and `dev` branches. +* `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. 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 From 1f10a9571d83750d4d6685b392f093d5b75124b2 Mon Sep 17 00:00:00 2001 From: michaelcdevin Date: Tue, 14 Jan 2025 11:14:32 -0700 Subject: [PATCH 3/3] fixed link --- docs/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/README.md b/docs/README.md index 5d547d16..ba80efba 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,7 +1,7 @@ # 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. 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`. +* `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.