From c938aeef9d3f7d5147bc870e101794acf909614e Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Wed, 29 Apr 2026 15:22:02 -0600 Subject: [PATCH 1/4] Docs docs: Add recommended VS Code setup. Resolves ESCOMP/CTSM#3952. --- .../esbonio-sphinx-buildcmd.png | 3 + .../working-with-documentation/index.rst | 1 + .../vscode-doc-editing-setup.md | 92 +++++++++++++++++++ 3 files changed, 96 insertions(+) create mode 100644 doc/source/users_guide/working-with-documentation/esbonio-sphinx-buildcmd.png create mode 100644 doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md diff --git a/doc/source/users_guide/working-with-documentation/esbonio-sphinx-buildcmd.png b/doc/source/users_guide/working-with-documentation/esbonio-sphinx-buildcmd.png new file mode 100644 index 0000000000..80a0006a1d --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/esbonio-sphinx-buildcmd.png @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:11f7d6821528a9b39a6de0a668f7b91a84ef2709d6276d68a4204258bb2b1e67 +size 15881 diff --git a/doc/source/users_guide/working-with-documentation/index.rst b/doc/source/users_guide/working-with-documentation/index.rst index 50735b4307..e3f34074fd 100644 --- a/doc/source/users_guide/working-with-documentation/index.rst +++ b/doc/source/users_guide/working-with-documentation/index.rst @@ -13,6 +13,7 @@ Working with CTSM Documentation bld-prev-docs-casper.md bld-prev-docs-mac.md bld-prev-docs-windows.md + vscode-doc-editing-setup.md docs-style-guide.md tips-for-working-with-markdown.md tips-for-working-with-rst.rst diff --git a/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md b/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md new file mode 100644 index 0000000000..8c3ae1abac --- /dev/null +++ b/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md @@ -0,0 +1,92 @@ +(vscode-docs-editing-setup)= + +# Recommended setup for editing docs in VS Code + +## Set up Python +The Python packages needed for this setup are listed at `doc/ctsm-docs_container/requirements.txt`. If you recently installed [the `ctsm_pylib` conda environment](https://escomp.github.io/CTSM/users_guide/using-clm-tools/using-ctsm-pylib.html), they will already be included there. Check like so: +```shell +conda activate ctsm_pylib +pip show myst-parser +``` + +If you see `WARNING: Package(s) not found: myst-parser`, you'll need to install the doc-building Python modules. With your conda environment activated (or in whatever other environment you want to use), from the top level of a CTSM checkout, do: +```shell +pip install -r doc/ctsm-docs_container/requirements.txt +``` + +You will need to provide the path to your Python binary in various VS Code settings detailed below. You can get that with `which python` (after loading the relevant conda environment, if needed). + +## Install required [VS Code extensions](https://code.visualstudio.com/docs/getstarted/extensions) + +1. [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) +2. [MyST-Markdown](https://marketplace.visualstudio.com/items?itemName=ExecutableBookProject.myst-highlight) +3. [Esbonio](https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio) + +## Change VS Code settings for Esbonio extension +```{important} +This setup will work only if you've opened the top level of a CTSM checkout as a [VS Code workspace](https://code.visualstudio.com/docs/editing/workspaces/workspaces). +``` + +Open VS Code's settings. You're going to change a few things, but note that VS Code can have up to three tabs (representing "scopes") across the top of the Settings page: User, Remote \[SSH: remotename], and Workspace. Below, we'll explain which setting should be set in which scope(s). Keep in mind that scopes going left to right get more specific, and a setting in a later (rightward) scope will always override the same setting in an earlier (leftward) scope. + +### Build command +`Esbonio > Sphinx: Build Command` in the Settings GUI: This is an annoying one. We want to tell it to use `sphinx-build doc/source ${defaultBuildDir} -c doc/doc-builder`, but each word there has to be its own element in a list. + +![](esbonio-sphinx-buildcmd.png) + +It might be easier to open your VS Code's `settings.json` file(s) for this. You'd simply add: +```json +"esbonio.sphinx.buildCommand": [ + "sphinx-build", + "doc/source", + "${defaultBuildDir}", + "-c", + "doc/doc-builder" +] +``` + +Note that it needs to be proper JSON syntax, though. So in context it looks like this if it's at the end of the file (your indentation may vary): +```json +"chat.disableAIFeatures": true, +"esbonio.sphinx.buildCommand": [ + "sphinx-build", + "doc/source", + "${defaultBuildDir}", + "-c", + "doc/doc-builder" +] +} +``` +Note the comma at the end of the preceding line, and the curly bracket on the very last line of the file. + +As far as which scope to use: If you're always or usually going to be using Esbonio to preview docs for CTSM, you should put this in the User scope. You can open your User `settings.json` by searching in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) for `user settings json`. For other projects using Esbonio, you will be able to set a Workspace-level `esbonio.sphinx.buildCommand` to override your User default. + +### Python command +`Esbonio > Sphinx: Python Command`. Do not get this confused with `Esbonio > Sphinx: Build Command` from above, or the similar `Esbonio > Server: Python Command`. This one you're going to *have* to edit in `settings.json`: +```json +"esbonio.sphinx.pythonCommand": "/path/to/your/python", +``` +The path is what you got from `which python` above. See the note about proper JSON syntax in "Build command" above. + +Which settings scope? +- If you're working on your local machine, User: Search in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) for `user settings json`. +- If you're working on a remote machine, Remote: Search in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) for `remote settings json`. + +### Finishing up +Once you've made those settings changes, reload the window (search `reload window` in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette)). + +## Previewing +This will take a while the first time you build the previews during a session. +1. (Optional but recommended, at least the first time) In the View menu, select Output. In the drop-down menu at the top right of the Output panel, select Esbonio. +2. Open a documentation source file (.rst or .md). +3. Search `Esbonio: Preview Documentation in Split Window` (or any subset of those words) in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). Select it and this should open a pane next to the documentation source file that is initially empty. +4. If you opened the Esbonio Output panel (or open it now), you'll see it working. This can take a while, especially if it's doing a clean build (such as the first time you do this). +5. Once it's done, the preview pane should fill in. + +When you make changes to and save a documentation source file, Esbonio will re-generate the preview for that file. This should be relatively quick, since it's not doing a clean build—just a new build of that file in particular. However, you may need to close and re-open the preview pane before you see your changes. Also, there are some types of changes you can make to one file that will affect *other* files (such as changing a section label that is cross-referenced in a different file). Esbonio will not know to rebuild those other files. To force a clean build, try the `Esbonio: Restart Language Server` command in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). Failing that, you can try deleting the directory referenced in the "The HTML pages are in" message printed in the Esbonio Output log. + +Some other tips: +- Once the preview is ready, you can scroll in either the source file or the preview and they will stay approximately in sync with each other. +- You should be able to open other source files and get their preview instantly. +- More info on features can be found on the [Esbonio VS Code Extension page](https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio) + From 677299481a89e297346ee81b57c46928276b1cba Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 7 May 2026 08:37:23 -0600 Subject: [PATCH 2/4] UG: Docs docs: VS Code: Esbonio settings --- doc/doc-builder | 2 +- .../working-with-documentation/vscode-doc-editing-setup.md | 2 +- src/fates | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/doc-builder b/doc/doc-builder index 243025ac2b..6607280dd7 160000 --- a/doc/doc-builder +++ b/doc/doc-builder @@ -1 +1 @@ -Subproject commit 243025ac2bb2050f0b2088b21351cca212248648 +Subproject commit 6607280dd7a96d5606fbd6e8abe547ac0da4d62f diff --git a/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md b/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md index 8c3ae1abac..970853533c 100644 --- a/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md +++ b/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md @@ -27,7 +27,7 @@ You will need to provide the path to your Python binary in various VS Code setti This setup will work only if you've opened the top level of a CTSM checkout as a [VS Code workspace](https://code.visualstudio.com/docs/editing/workspaces/workspaces). ``` -Open VS Code's settings. You're going to change a few things, but note that VS Code can have up to three tabs (representing "scopes") across the top of the Settings page: User, Remote \[SSH: remotename], and Workspace. Below, we'll explain which setting should be set in which scope(s). Keep in mind that scopes going left to right get more specific, and a setting in a later (rightward) scope will always override the same setting in an earlier (leftward) scope. +Open VS Code's settings. (To restrict the list to only settings related to this setup, you can access the Esbonio settings via the gear icon on its item in the Extensions menu.) You're going to change a few things, but note that VS Code can have up to three tabs (representing "scopes") across the top of the Settings page: User, Remote \[SSH: remotename], and Workspace. Below, we'll explain which setting should be set in which scope(s). Keep in mind that scopes going left to right get more specific, and a setting in a later (rightward) scope will always override the same setting in an earlier (leftward) scope. ### Build command `Esbonio > Sphinx: Build Command` in the Settings GUI: This is an annoying one. We want to tell it to use `sphinx-build doc/source ${defaultBuildDir} -c doc/doc-builder`, but each word there has to be its own element in a list. diff --git a/src/fates b/src/fates index 1399b6135a..b17b0bdff2 160000 --- a/src/fates +++ b/src/fates @@ -1 +1 @@ -Subproject commit 1399b6135aadef221a4f28186cde75b7f12a35c1 +Subproject commit b17b0bdff243c6782414e191736fb0d15935a5c7 From fc2287d802dde780031458a2e10e349c08517be7 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 7 May 2026 08:45:50 -0600 Subject: [PATCH 3/4] UG: Docs docs: VS Code: Word wrap. --- .../users_guide/working-with-documentation/docs-style-guide.md | 2 +- .../working-with-documentation/vscode-doc-editing-setup.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/source/users_guide/working-with-documentation/docs-style-guide.md b/doc/source/users_guide/working-with-documentation/docs-style-guide.md index 448481630d..8b7aa4fc31 100644 --- a/doc/source/users_guide/working-with-documentation/docs-style-guide.md +++ b/doc/source/users_guide/working-with-documentation/docs-style-guide.md @@ -1,4 +1,4 @@ -(docs-style-guide)= +(docs-style-guide-section)= # Documentation style guide diff --git a/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md b/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md index 970853533c..9a2d139bf8 100644 --- a/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md +++ b/doc/source/users_guide/working-with-documentation/vscode-doc-editing-setup.md @@ -86,7 +86,7 @@ This will take a while the first time you build the previews during a session. When you make changes to and save a documentation source file, Esbonio will re-generate the preview for that file. This should be relatively quick, since it's not doing a clean build—just a new build of that file in particular. However, you may need to close and re-open the preview pane before you see your changes. Also, there are some types of changes you can make to one file that will affect *other* files (such as changing a section label that is cross-referenced in a different file). Esbonio will not know to rebuild those other files. To force a clean build, try the `Esbonio: Restart Language Server` command in the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette). Failing that, you can try deleting the directory referenced in the "The HTML pages are in" message printed in the Esbonio Output log. Some other tips: +- If you see long lines in the editor that require you to scroll far to the right, search the [Command Palette](https://code.visualstudio.com/docs/getstarted/userinterface#_command-palette) for "word wrap" and select `View: Toggle Word Wrap`. These long lines are intentional (see [style guide](#docs-style-guide-section)). - Once the preview is ready, you can scroll in either the source file or the preview and they will stay approximately in sync with each other. - You should be able to open other source files and get their preview instantly. - More info on features can be found on the [Esbonio VS Code Extension page](https://marketplace.visualstudio.com/items?itemName=swyddfa.esbonio) - From 22c9efcdf8ed04e1733e869e82ae590731b53f95 Mon Sep 17 00:00:00 2001 From: Sam Rabin Date: Thu, 7 May 2026 08:52:15 -0600 Subject: [PATCH 4/4] Fix fates checkout --- src/fates | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/fates b/src/fates index b17b0bdff2..1399b6135a 160000 --- a/src/fates +++ b/src/fates @@ -1 +1 @@ -Subproject commit b17b0bdff243c6782414e191736fb0d15935a5c7 +Subproject commit 1399b6135aadef221a4f28186cde75b7f12a35c1