Live preview of docs in VSCode

[samsrabin]

I've been doing a bit of work on the docs and finally worked out a good way to preview them from within VSCode. It takes a bit of effort, but once it's working it's pretty nice.

Instructions

The first step is to install the reStructuredText extension for VSCode. Their website has some documentation that's helpful for understanding what it's useful for and how to set it up (note especially Prerequisites and Configuration). I'll describe my process here.

2. Set up a clean virtual environment for VSCode to use for this. I used mamba but it should work equally well with conda. Instructions updated 2024-11-01.

mamba create --name vscode-restructuredtext
mamba activate vscode-restructuredtext
mamba install -c conda-forge python esbonio sphinx-rtd-theme sphinx-mdinclude

3. Set VSCode to use the new virtual environment as the Python interpreter: Open the Command Palette and search for Python: Select Interpreter.
4. In VSCode Workspace settings:

• Set Esbonio › Server: Python Path to the path you get when you do which python in your vscode-restructuredtext environment.
• Set Esbonio › Sphinx: Conf Dir to ${workspaceFolder}/doc/source.
• Optional: Set Esbonio › Sphinx: Build Dir to ${workspaceFolder}/.vscode/_build_esbonio_sphinx/. This will make it so that the generated HTML files etc. are ignored by Git.
• Optional: Uncheck Esbonio › Sphinx: Force Full Build.
• Optional: Set Esbonio › Sphinx: Num Jobs to 0. This will allow sphinx-build to automatically determine how many processes to use when generating the HTML.

5. I quit and reopened VSCode at this point, but I'm not sure that's necessary.
6. From the View menu, click Output, then in that panel's dropdown menu select Esbonio Language Server. This will show progress and messages from the generation process.
7. If it's not already going, click "esbonio" at the bottom right of the VSCode window (see my screenshot above). This should start the build process. The first time will take a while!
8. Once it's done, open a .rst file from the docs (e.g., doc/source/tech_note/Methane/CLM50_Tech_Note_Methane.rst). Open the Command Palette and do reStructured Text: Open Preview to the Side. This should show the Tech Note we all know and love!
9. Try making some change, like adding "Sam rocks" somewhere in the text. When you save, it should kick off a re-render.

Tweaking the .rst files

There are some things that didn't work right until I actually edited the docs themselves.

Mathematical symbols and equations were mostly or all broken:

I solved this by deleting the 'sphinx.ext.imgmath', line from doc/source/conf.py:

Some equations still didn't render:

I solved this by deleting all instances of \kern-\nulldelimiterspace in all .rst files:

Caveats

Clicking links in the Live Preview opens my web browser to some unfindable page.

There are some warnings about failed references that I want to track down:

doc/source/lilac/obtaining-building-and-running/setting-ctsm-runtime-options.rst:107: WARNING: undefined label: 'creating-domain-files'
doc/source/lilac/obtaining-building-and-running/setting-ctsm-runtime-options.rst:111: WARNING: undefined label: 'creating-surface-datasets'
doc/source/lilac/obtaining-building-and-running/setting-ctsm-runtime-options.rst:137: WARNING: undefined label: 'customizing-a-case'
doc/source/tech_note/Introduction/CLM50_Tech_Note_Introduction.rst:52: WARNING: Failed to create a cross reference. Any number is not assigned: figure-mosart-conceptual-diagram
doc/source/tech_note/MOSART/CLM50_Tech_Note_MOSART.rst:28: WARNING: Failed to create a cross reference. Any number is not assigned: figure-mosart-conceptual-diagram
doc/source/users_guide/using-clm-tools/creating-input-for-surface-dataset-generation.rst:114: WARNING: undefined label: 'figure mksurfdatamap'
doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst:19: WARNING: undefined label: 'figure global_domain'
doc/source/users_guide/using-clm-tools/creating-surface-datasets.rst:19: WARNING: undefined label: 'figure mksurfdatamap'

Questions

• Would it be possible for us to move away from relying on sphinx.ext.imgmath? The base sphinx seems to include math rendering capabilities now.
• Was \kern-\nulldelimiterspace doing something important?
• Would anyone else be willing to try and set this up? I'd like to know if there are steps I forgot to add or other roadblocks.

[ekluzek]

@olyson do you know the answer to @samsrabin questions above?

[billsacks]

Cool, @samsrabin - thanks for writing this up!

I'm not sure about this:

Would it be possible for us to move away from relying on sphinx.ext.imgmath?

But I do know that this line:

imgmath_image_format = 'svg'

was important to get better-looking equations in the rendered documentation. I'm not sure whether that relies on the sphinx.ext.imgmath package.

[samsrabin]

Thanks, Bill! I tried deleting that line just now, and indeed it broke all the equations. However, weirdly, it doesn't seem to rely on sphinx.ext.imgmath, as just deleting the latter works fine. I'm thinking maybe Esbonio doesn't support sphinx.ext.imgmath because the functionality, including imgmath_image_format, is now included in base Sphinx.

[samsrabin]

Actually, no, I was wrong—somehow I had put sphinx.ext.imgmath back in conf.py. Removing both that line and imgmath_image_format seems to work fine.

[billsacks]

If you want to experiment with removing the imgmath_image_format line, the important thing to check is the clarity of the equations in the generated html that we push up to https://escomp.github.io/ctsm-docs . Before that change, equations were generated as png files that had pretty poor quality. Changing to svg led to much crisper display of the equations - though a downside, if I remember correctly, was significantly longer documentation build times.

[samsrabin]

Good point. The quality looks fine to me; what do you think? Here's an example .html file.

[billsacks]

That looks good to me, too. Maybe the earlier issues are better now?