From 1de4c58a64101ceefc4908aa2c6a49d40b18dbce Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:15:08 -0600 Subject: [PATCH 1/8] Makefile: Delete latexpdf bit with tech_note ref. --- Makefile | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/Makefile b/Makefile index 5a74413..2048c35 100644 --- a/Makefile +++ b/Makefile @@ -22,19 +22,6 @@ fetch-images: .PHONY: help fetch-images Makefile -# For the pdf, we only build the tech note, but use the conf.py file in -# the top-level source directory (the -c option says where to find -# conf.py). Note that we also override the setting of -# numfig_secnum_depth in order to have figure numbering as desired in -# the pdf, given that the pdf just contains the tech note, so doesn't -# have the top-level numbering present in the web documentation (where -# top-level section 1 is the User's Guide and section 2 is the Tech -# Note). -# -# The use of $(0) is as in the catch-all target. -latexpdf: - $(SPHINXBUILD) -M $@ "$(SOURCEDIR)/tech_note" "$(BUILDDIR)" -c "$(DIRWITHCONFPY)" -D numfig_secnum_depth=1 $(SPHINXOPTS) $(O) - # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile From c18f6ff45d41e1346c07d7823e37b90e31a2d3f8 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:21:53 -0600 Subject: [PATCH 2/8] Add more "When you copy this into your repo" comments. --- substitutions.py | 5 +++++ version_list.py | 2 ++ 2 files changed, 7 insertions(+) diff --git a/substitutions.py b/substitutions.py index c0c4c55..c07ab61 100644 --- a/substitutions.py +++ b/substitutions.py @@ -6,6 +6,8 @@ # |version| and |release|, also used in various other places throughout the # built documents. +# When you copy this into your repo, update all values as needed. + # pylint: disable=invalid-name ################################# @@ -66,6 +68,9 @@ ### Purely custom variables ### ############################### +# When you copy this into your repo, you can keep these as examples if you want, but you can also +# just delete them. + nonparamfile_disclaimer_md = ( "**Note:** The values here should be up-to-date with those used in {{version_label}}," " but there may be mistakes." diff --git a/version_list.py b/version_list.py index 6b951b6..602aeaa 100644 --- a/version_list.py +++ b/version_list.py @@ -30,6 +30,8 @@ # ref=... refers to the branch in the repo with the frozen docs. The short_name will show up in # URL slugs and maybe elsewhere; it doesn't have to match the ref. display_name will be shown in # the version picker drop-down. + # When you copy this into your repo, replace this with any and all frozen versions you wish to + # build. DocsVersion( short_name="dummy-version", display_name="Dummy version", From 11b0280a64b1f9889d8cf888a0596e11ff2b30f9 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:28:43 -0600 Subject: [PATCH 3/8] Add instructions for incorporating doc-builder into your own repo. --- source/incorporating-doc-builder.md | 53 +++++++++++++++++++++++++++++ source/index.md | 3 ++ source/markdown.md | 4 +++ 3 files changed, 60 insertions(+) create mode 100644 source/incorporating-doc-builder.md diff --git a/source/incorporating-doc-builder.md b/source/incorporating-doc-builder.md new file mode 100644 index 0000000..be16887 --- /dev/null +++ b/source/incorporating-doc-builder.md @@ -0,0 +1,53 @@ +# Incorporating doc-builder into your repo + +## Required structure + +doc-builder expects your repo's documentation to have a certain structure. Specifically, from the top level of your repo, it expects at least the following: + +``` +├── doc +│   ├── build_docs +│   ├── build_docs_to_publish +│   ├── doc-builder/ +│   ├── Makefile +│   ├── source/ +│   │   └── index.rst OR index.md +│   ├── substitutions.py +│   └── version_list.py +``` + +### `build_docs*` scripts + +These are the scripts you will be calling to actually build the documentation. They are essentially just wrappers around tools in doc-builder. + +Copy these from `doc-builder/`. + +### doc-builder + +This should be a submodule of your repository, managed either as a standard Git submodule or via [git-fleximod](https://github.com/ESMCI/git-fleximod). + +### Makefile + +This is where the Sphinx build commands are actually defined. + +Copy this from `doc-builder/`. + +### source/ + +This is where your documentation will live. It requires at least a file called `index.md` or `index.rst`, depending on whether you prefer MyST Markdown or reStructuredText. During the documentation build, Sphinx will try to include any file you put in here (recursively) with the `.md` or `.rst` extensions. See the [doc-builder `doc/source/`](https://github.com/ESMCI/doc-builder/tree/master/source) for an example. + +### substitutions.py + +This is a Python file defining certain string variables that Sphinx will look for during the build process. The contents of these variables will be incorporated into your built documentation, substituting e.g. `|variable_name|` [in a reStructuredText file](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions) (or `{{variable_name}}` [in a Markdown file](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2)) with the defined string. There are some that Sphinx always wants, such as `project` and `copyright`, but you can also define custom ones. See the [doc-builder `substitutions.py`](https://github.com/ESMCI/doc-builder/blob/master/substitutions.py) for an example. + +Copy this from `doc-builder/`, then customize it as needed. + +### version_list.py + +This is a Python file defining the versions of your documentation to be displayed in the menu at lower left. + +Copy this from `doc-builder/`, then customize it as needed. + +## Customizing files copied from doc-builder + +In the files that you copy from doc-builder, there are various places you'll need to make changes in order to make them compatible with your repo. Search for "When you copy this into your repo" to find them all, and make the designated changes. diff --git a/source/index.md b/source/index.md index 08d3f6d..3dc37ff 100644 --- a/source/index.md +++ b/source/index.md @@ -1,6 +1,9 @@ # doc-builder test documentation ```{toctree} +:maxdepth: 1 + markdown.md reStructuredText.rst +incorporating-doc-builder.md ``` \ No newline at end of file diff --git a/source/markdown.md b/source/markdown.md index a68fd54..b0f0af3 100644 --- a/source/markdown.md +++ b/source/markdown.md @@ -1,3 +1,7 @@ +--- +orphan: true +--- + # Info (markdown) This tool wraps the build command to build sphinx-based documentation. From 5d827d2d4ca4f9b9cb16b5b3e305402f796cb053 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:32:03 -0600 Subject: [PATCH 4/8] Hide "info" docs. --- source/index.md | 2 -- source/testing_only/README | 1 + source/{ => testing_only}/markdown.md | 0 source/{ => testing_only}/reStructuredText.rst | 2 ++ 4 files changed, 3 insertions(+), 2 deletions(-) create mode 100644 source/testing_only/README rename source/{ => testing_only}/markdown.md (100%) rename source/{ => testing_only}/reStructuredText.rst (99%) diff --git a/source/index.md b/source/index.md index 3dc37ff..dcf960c 100644 --- a/source/index.md +++ b/source/index.md @@ -3,7 +3,5 @@ ```{toctree} :maxdepth: 1 -markdown.md -reStructuredText.rst incorporating-doc-builder.md ``` \ No newline at end of file diff --git a/source/testing_only/README b/source/testing_only/README new file mode 100644 index 0000000..1b3d03a --- /dev/null +++ b/source/testing_only/README @@ -0,0 +1 @@ +This directory contains files we don't want easily reachable in the published documentation; they're just for testing purposes. They WILL be available if someone knows the path, though! diff --git a/source/markdown.md b/source/testing_only/markdown.md similarity index 100% rename from source/markdown.md rename to source/testing_only/markdown.md diff --git a/source/reStructuredText.rst b/source/testing_only/reStructuredText.rst similarity index 99% rename from source/reStructuredText.rst rename to source/testing_only/reStructuredText.rst index c1204a4..420723e 100644 --- a/source/reStructuredText.rst +++ b/source/testing_only/reStructuredText.rst @@ -1,3 +1,5 @@ +:orphan: + *********************** Info (reStructuredText) *********************** From 5c0898100f3403166e4d0fef681a63436a1ee186 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:41:33 -0600 Subject: [PATCH 5/8] Add documentation about GitHub workflows. --- source/incorporating-doc-builder.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/source/incorporating-doc-builder.md b/source/incorporating-doc-builder.md index be16887..335ac2b 100644 --- a/source/incorporating-doc-builder.md +++ b/source/incorporating-doc-builder.md @@ -48,6 +48,18 @@ This is a Python file defining the versions of your documentation to be displaye Copy this from `doc-builder/`, then customize it as needed. +## GitHub workflows + +There are various useful GitHub workflows at `doc-builder/.github/workflows/docs*yml`. These provide automatic testing and publication of your docs. If you'd like, copy them to your repo's `.github/workflows/` and customize them as needed. (Don't include any workflows except the `docs*yml` ones; the others are only useful in the doc-builder repo itself.) + +Your repository will probably need to be public if you want Workflows to run, at least for free. You will also need to enable Actions in your repo's settings. + +### Automatic publication + +The `docs-build-and-deploy.yml` workflow will automatically publish your documentation to GitHub Pages whenever you push (or merge a PR) to one of your documentation branches. To enable this, go to "Pages" in your repo's settings, then make sure "Source" is set to "GitHub Actions." + +If you're not going to use automatic publication, do not include `docs-build-and-deploy.yml` in your `.github/workflows/`. + ## Customizing files copied from doc-builder In the files that you copy from doc-builder, there are various places you'll need to make changes in order to make them compatible with your repo. Search for "When you copy this into your repo" to find them all, and make the designated changes. From fdc1b7624c8cf3e56a5471624b10229b0f8b4551 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:49:30 -0600 Subject: [PATCH 6/8] Porting docs: Delete existing files. --- source/incorporating-doc-builder.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/source/incorporating-doc-builder.md b/source/incorporating-doc-builder.md index 335ac2b..4e1d623 100644 --- a/source/incorporating-doc-builder.md +++ b/source/incorporating-doc-builder.md @@ -20,7 +20,7 @@ doc-builder expects your repo's documentation to have a certain structure. Speci These are the scripts you will be calling to actually build the documentation. They are essentially just wrappers around tools in doc-builder. -Copy these from `doc-builder/`. +Copy these from `doc-builder/`; you should probably not customize them. ### doc-builder @@ -30,7 +30,7 @@ This should be a submodule of your repository, managed either as a standard Git This is where the Sphinx build commands are actually defined. -Copy this from `doc-builder/`. +Copy this from `doc-builder/`. If your repo already has a Makefile somewhere in `doc/`, see if it contains anything you might want to add to doc-builder's, then delete it. ### source/ @@ -40,13 +40,13 @@ This is where your documentation will live. It requires at least a file called ` This is a Python file defining certain string variables that Sphinx will look for during the build process. The contents of these variables will be incorporated into your built documentation, substituting e.g. `|variable_name|` [in a reStructuredText file](https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#substitutions) (or `{{variable_name}}` [in a Markdown file](https://myst-parser.readthedocs.io/en/latest/syntax/optional.html#substitutions-with-jinja2)) with the defined string. There are some that Sphinx always wants, such as `project` and `copyright`, but you can also define custom ones. See the [doc-builder `substitutions.py`](https://github.com/ESMCI/doc-builder/blob/master/substitutions.py) for an example. -Copy this from `doc-builder/`, then customize it as needed. +Copy this from `doc-builder/`, then customize it as needed. If your repo already has a `substitutions.py` somewhere in `doc/`, use that as a guide for your customizations, then delete it. ### version_list.py This is a Python file defining the versions of your documentation to be displayed in the menu at lower left. -Copy this from `doc-builder/`, then customize it as needed. +Copy this from `doc-builder/`, then customize it as needed. If your repo already has a `version_list.py` somewhere in `doc/`, use that as a guide for your customizations, then delete it. ## GitHub workflows @@ -63,3 +63,7 @@ If you're not going to use automatic publication, do not include `docs-build-and ## Customizing files copied from doc-builder In the files that you copy from doc-builder, there are various places you'll need to make changes in order to make them compatible with your repo. Search for "When you copy this into your repo" to find them all, and make the designated changes. + +## Things to delete from your repo's pre-existing `docs/` + +In addition to the files you're copying and customizing from doc-builder, if your repo already contains `conf.py` somewhere in `doc/`, delete it to avoid confusion. If there are things in there that `doc-builder/conf.py` doesn't have, and your existing docs won't build (either correctly or at all) after deleting your existing `conf.py`, [file a doc-builder issue](https://github.com/ESMCI/doc-builder/issues/new). Do NOT change `doc-builder/conf.py`. From 69431a87dcaefd21ffadd6eb77b77719b6494cab Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 16:57:38 -0600 Subject: [PATCH 7/8] Porting docs: More files to delete; .gitignore tips. --- source/incorporating-doc-builder.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/source/incorporating-doc-builder.md b/source/incorporating-doc-builder.md index 4e1d623..dc53143 100644 --- a/source/incorporating-doc-builder.md +++ b/source/incorporating-doc-builder.md @@ -67,3 +67,13 @@ In the files that you copy from doc-builder, there are various places you'll nee ## Things to delete from your repo's pre-existing `docs/` In addition to the files you're copying and customizing from doc-builder, if your repo already contains `conf.py` somewhere in `doc/`, delete it to avoid confusion. If there are things in there that `doc-builder/conf.py` doesn't have, and your existing docs won't build (either correctly or at all) after deleting your existing `conf.py`, [file a doc-builder issue](https://github.com/ESMCI/doc-builder/issues/new). Do NOT change `doc-builder/conf.py`. + +If your repo already has `_static/` and/or `_templates/` directories somewhere in `doc/`, delete them. doc-builder has its own versions. + +If you're planning to use automatic publication and your repo already contains built documentation, delete it. + +## Things to add to `.gitignore` + +Consider adding the following to your repo's `.gitignore` file: +- `doc/_build` and `doc/_publish`: Directories created by suggested calls of the `build_docs*` scripts. +- `doc/__pycache__`: Python cache. From 0d78657faf7ff9d8398315e4a987358a64a7d185 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 25 Jun 2026 17:05:55 -0600 Subject: [PATCH 8/8] Improve docs landing page. --- source/index.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/source/index.md b/source/index.md index dcf960c..555539f 100644 --- a/source/index.md +++ b/source/index.md @@ -1,4 +1,6 @@ -# doc-builder test documentation +# doc-builder documentation + +doc-builder is a tool you can use to simplify the process of building and publishing your documentation using Sphinx. Find more detailed documentation linked below. ```{toctree} :maxdepth: 1