1.10.1. Working with the CTSM documentation
If you're reading this page, you're probably interested in making an improvement to this CTSM documentation website—thank you! Please read this page thoroughly before starting to make it as smooth a process as possible.
1.10.1.1. How the documentation works
The documentation starts life as files in the doc/source/tech_note/ and doc/source/users_guide/ directories. These files are written in a mixture of what are called "markup languages." You may already be familiar—for better or for worse—with the LaTeX markup language. Fortunately, our documentation is simpler than that. It was originally written entirely in reStructuredText, and it still mostly is, as you can tell by the predominance of .rst files. However, it's also possible to write Markdown documents (.md), which is nice because it's a much simpler and more widespread format (although see Tips for working with Markdown). If you've formatted text on GitHub, for instance, you've used Markdown.
During the "build" process, these files are converted to HTML webpages using a tool called Sphinx. This creates a directory with HTML files that can then be "previewed" to make sure they look right. When you submit a pull request (PR; see Contribution guidelines below), tests will automatically run to make sure your changed documentation builds with no errors. Then, when your PR is merged to the main CTSM branch, it will be rebuilt and published automatically.
1.10.1.2. Contribution guidelines
We use the CTSM GitHub repo to track issues with the documentation and bring in changes. Please have a look at our "How to contribute" readme for some general guidelines.
If you have found a problem with the documentation but aren't able to fix it immediately, or if you're not sure whether something is truly a problem or how to fix it, please file an issue.
If you've made changes that you'd like us to bring in, you can file a pull request (PR; "New pull request" button at that link). Please try to avoid filing many small documentation PRs in a short time, as it's easier for the maintenance team if you combine similar edits into one larger PR. For example, several typo fixes in a file or across files would be a good single PR. You can also mark a PR as "draft" if you think you may be adding more to it, or if you think it's otherwise not ready for review.
Whenever you submit a documentation PR or commit new changes to one, automated testing will check the updated documentation for any errors. If you get failures, please try to diagnose and fix them; see Common doc build errors and how to handle them for tips. If you resolve the errors, add a comment on your PR saying so, and one of the CTSM software engineers will have a look.
1.10.1.3. Editing the documentation
First, you will need a clone of CTSM to get all the documentation files and infrastructure. Once you have that, editing the documentation is as simple as editing the source file for the page you want to edit, in doc/source/. You can find the exact path under that directory by appending the part of the webpage URL after https://escomp.github.io/CTSM/ and replacing .html with either .rst (most likely) or .md. So if I wanted to change this page (URL https://escomp.github.io/CTSM/users_guide/working-with-documentation/docs-intro-and-recommended.html), I would look in the directory doc/source/users_guide/working-with-documentation for docs-intro-and-recommended.rst or .md.
Make sure to use either reStructuredText or Markdown syntax, depending on the file's extension (.rst or .md, respectively). You can mix some reStructuredText into Markdown files, but generally not the other way around. For more information, see:
We strongly recommend building and previewing the docs yourself as you're editing them, or at least before requesting review on your PR. You can find instructions for doing so here: