Repository navigation
Conversation
climbfuji
reviewed
Sep 23, 2026
climbfuji
left a comment
climbfuji
left a comment
Collaborator
There was a problem hiding this comment.
I prefer converting it to a markdown document that can be viewed directly in any modern IDE (VSCode, Xcode, ...) and on GitHub.
mkavulich
changed the title
… site Splits the single StandardNamesRules.rst file verbatim into per-chapter files under docs/chapters/, adds Sphinx scaffolding (conf.py, index.rst, requirements.txt) and a top-level .readthedocs.yaml so the rules can be built and published on Read the Docs. StandardNamesRules.rst is replaced with a stub pointing to the new docs/ location, and README.md is updated to match. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- naming_rules.rst: repair a malformed grid table (missing column divider in the top border, a stray space instead of a dash in a row separator) that was merging/misrendering the control-oriented variables table; also add the missing colon on the ".. _Rules" target. - qualifiers.rst: escape trailing underscores in "surface_", "since_", "over_", and "reset_every_" so they render as plain text instead of being parsed as broken hyperlink references. - technical_specifications.rst: use "::" instead of ":" to introduce the exner_function XML snippet so it renders as a code block instead of a garbled block quote/definition list. - index.rst: lengthen the title over/underline to match the title text length. No wording changes; docs/ now builds with zero Sphinx warnings. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace the three plain hyperlinks to wiki-hosted PNGs in naming_rules.rst with .. figure:: directives, so the images render inline on the page instead of requiring a click-through. Each figure gets descriptive alt text and a caption; the images continue to be served from raw.githubusercontent.com rather than being vendored into the repo. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
mkavulich
force-pushed
the
feature/readthedocs
branch
from
October 8, 2026 19:19
93dcc95 to
4522ec5
Compare
docs/chapters/naming_rules.rst was split off before #157 (surface/ocean-vs-sea/skin-temperature terminology) was merged to main on a sibling branch, so it never picked up that PR's two wording changes: the layer/interface definition, and the skin_temperature_at_toa clarification. Verified these are the only two substantive content differences between main's StandardNamesRules.rst and the current chapter files; everything else that looked different was prior styling work on this branch. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adds docs/Makefile with html/clean targets, matching the docs/html build-output convention already documented in README.md and StandardNamesRules.rst (commit 826ba87). Both docs now say 'cd docs && make html' instead of the raw sphinx-build invocation; docs/html/ is gitignored. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Collaborator
|
I missed the conversation at today's meeting about preferred format (readthedocs vs markdown vs. ...) - any conclusion? |
…ference Merges qualifiers.rst, common_components.rst, aliases.rst, and units.rst into a single reference.rst chapter, with each former chapter becoming a section (heading levels demoted one notch: former = underlines become -, former - become ^, and a new 4th level " is introduced for the Prefixes/Suffixes/Infixes under each Qualifiers category). No cross-reference edits were needed in naming_rules.rst or technical_specifications.rst: Sphinx's :ref: resolves by label (_transformations:, _units_section:, _Aliases:), not by file path, so those links keep working unchanged now that the labels live in a different file. Updated docs/index.rst's toctree (6 entries -> 3) and the StandardNamesRules.rst stub's file listing to match. Verified: zero-warning build, and diffed reference.rst against the four original files to confirm only heading markers and labels changed -- no prose content was altered. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Renames docs/chapters/reference.rst to vocabulary.rst and retitles it 'Vocabulary and Units' to better cover its contents (qualifiers, common components, aliases, and units). Updates docs/index.rst's toctree and the StandardNamesRules.rst stub to match. No :ref: label changes needed -- the section labels (_qualifiers:, _transformations:, _Aliases:, _units_section:) are unaffected by the filename/title change. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
The current plain .rst document (StandardNameRules.rst) gives us some formatting capabilities over a plain .txt file, but has major limitations. A big one is the lack of embedded images, and limited linking capabilities. Sphinx-generated html documents give us these capabilities, as well as an easily-referenceable and versioned HTML build of the standard name rules, hosted on ReadTheDocs.
This PR moves the rules as-is to the docs/chapters directory, with the only changes being formatting and splitting the rules into multiple files for different chapters. The build for this branch can be found at https://esm-standard-names.readthedocs.io/en/feature-readthedocs/index.html
Issues
See #163