Adopt more easily viewed documentation format(s)
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 30/100
- Issue type
- Documentation
- Clarity
- Needs clarification
- Activity status
- Active
- Tech stack
- markdown, python
- Domain
- documentation
Research direction
Read the existing StandardNamesRules.rst and the proposed Markdown chapters under docs/chapters, then compare the ReadTheDocs build linked in the issue. The discussion asks for feedback on the format and approach, but does not settle what change should be made or define completion; first establish the preferred direction with the maintainers.
Written by the indexing model from the issue text.
Description
Currently the standard name rules are contained in a restructured text (.rst) document (StandardNameRules.rst); this gives us some formatting capabilities over a plain .txt file (when parsed appropriately), but has major limitations. While the .rst file can be parsed into a formatted file, this is not done natively on GitHub, so features like, for example, embedded images can not be viewed without parsing in a separate program.
I originally opened #159 thinking that a good way to view the documentation would be via a ReadTheDocs build, breaking up the existing .rst into chapters and adopting Sphinx-specific format for embedded images, links, and tables. However, as @climbfuji pointed out, it would also be useful to have a Markdown format that can be viewed both on Github and locally in IDEs. So with Claude's help I created the branch feature/readthedocs_md that uses MarkDown files instead; these are still built with ReadTheDocs to take advantage of their html parsing, but now the raw files can also be easily viewed on GitHub with most of the features intact:
- https://github.com/ESCOMP/ESMStandardNames/blob/feature/readthedocs_md/docs/chapters/naming_rules.md
- https://github.com/ESCOMP/ESMStandardNames/blob/feature/readthedocs_md/docs/chapters/technical_specifications.md
- https://github.com/ESCOMP/ESMStandardNames/blob/feature/readthedocs_md/docs/chapters/vocabulary.md
ReadTheDocs build for markdown: https://esm-standard-names.readthedocs.io/en/feature-readthedocs_md/
@climbfuji and others, let me know your thoughts!
- Dominant language
- Python
- Stars
- 9
- Forks
- 17
- Avg merge
- 16d 22m
- Merged PRs (30d)
- 1
Getting set up
- No Dockerfile or Docker Compose file
- Has a pull request template
- No contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ESCOMP/ESMStandardNames
-
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
ESCOMP/ESMStandardNames#160 ·
-
Comments do not appear alongside the standard name definitions in either Metadata filePossibly taken @mkavulich claimed this 17 days ago. Openbug
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
ESCOMP/ESMStandardNames#158 ·
-
Difficulty 3/5 1-2 days Newbie friendliness 56/100
ESCOMP/ESMStandardNames#161 ·
-
Difficulty 4/5 3-5 days Newbie friendliness 45/100
ESCOMP/ESMStandardNames#146 ·
-
Mapping to Grib TablesMay be free again @climbfuji claimed this 171 days ago, and no pull request is open. Open
ESCOMP/ESMStandardNames#120 · 2 comments · 1 assignee ·
All issues in ESCOMP/ESMStandardNames
Similar issues
-
The changelog workflow excludes otelbot but not dependabot, so every Dependabot pull request fails the changelog checkPossibly taken @ocelotl claimed this today. Open
Difficulty 1/5 Under an hour Newbie friendliness 82/100
open-telemetry/opentelemetry-python#5825 ·
Maintainers usually reply within 2 days
-
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
cuga-project/cuga-agent#1020 ·
Maintainers usually reply within 2 days
-
Difficulty 1/5 Under an hour Newbie friendliness 70/100
microsoft/playwright#43640 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
stac-utils/stac-fastapi-elasticsearch-opensearch#965 ·
Maintainers usually reply within 2 days
-
from-review-extraction library privacy python severity:suggested
Difficulty 2/5 1-3 hours Newbie friendliness 83/100
LearningCircuit/local-deep-research#7951 ·
Maintainers usually reply within 2 days