menzel
ba27af5a71
Add docs/developer/editing_docs.md documenting the MyST/Sphinx conventions
for this site: page anatomy (cross-reference label + single H1), language-
tagged code fences, admonitions, cross-references, the {download} role for
non-image files, the {figure} directive, and how to add a page to a toctree.
Also covers local preview, the merge-then-RTD-build flow, and pitfalls
(broken refs are warnings, public visibility, placeholder consistency).
Turn the empty developer.md stub into a landing page with a toctree and a
card linking to the new guide.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
144 lines
4.5 KiB
Markdown
144 lines
4.5 KiB
Markdown
(developer.editing_docs)=
|
|
|
|
# Editing the documentation
|
|
|
|
This documentation is built with [Sphinx](https://www.sphinx-doc.org) using the
|
|
[MyST](https://myst-parser.readthedocs.io) Markdown parser, and hosted on
|
|
[Read the Docs](https://sls-csaxs.readthedocs.io). The source lives in `docs/` of
|
|
the `csaxs_bec` repository.
|
|
|
|
:::{important}
|
|
The pages use **MyST Markdown**, which is a superset of CommonMark — *not*
|
|
Gitea/GitHub-flavored Markdown. Most plain Markdown works as expected, but the
|
|
conventions below are specific to this build and need to be followed for links,
|
|
admonitions, and navigation to render correctly.
|
|
:::
|
|
|
|
## How a change goes live
|
|
|
|
There are two ways to propose an edit:
|
|
|
|
- **In the browser (easiest, no git required).** Open the page in Gitea and click
|
|
**Edit**. Gitea commits your change to a new branch and opens a pull request for you;
|
|
if you do not have write access it first creates a personal fork automatically.
|
|
- **Locally.** Create a branch, edit the `.md` files under `docs/`, push, and open a
|
|
pull request.
|
|
|
|
A documentation maintainer then reviews and merges the pull request into `main`.
|
|
Merging is restricted to a few people by design — opening the pull request is all that
|
|
is expected of an author.
|
|
|
|
Once merged, the `.gitea/workflows/rtd_deploy.yml` action fires on the push to `main`
|
|
and triggers a Read the Docs build of the `latest` version; the site updates a minute
|
|
or two later. Nothing needs to be built or uploaded by hand.
|
|
|
|
## Anatomy of a page
|
|
|
|
Every content page starts with a **cross-reference label** followed by a single
|
|
top-level heading:
|
|
|
|
```md
|
|
(user.saxs.data_analysis)=
|
|
# Data analysis
|
|
```
|
|
|
|
- The label `(user.saxs.data_analysis)=` is what other pages, the section landing
|
|
pages, and the `{ref}` role link to. **Do not delete or rename it** without
|
|
updating every reference, or links silently break.
|
|
- The `# Title` is the page's H1. Sphinx needs exactly one; section pages do not
|
|
inherit a title from the file name the way the old wiki did.
|
|
|
|
## Conventions
|
|
|
|
### Code blocks — always tag the language
|
|
|
|
Use a language on every fenced block so syntax highlighting and the copy button work:
|
|
|
|
````md
|
|
```bash
|
|
module load Python/3.11.11
|
|
pip install "pyFAI[gui]"
|
|
```
|
|
````
|
|
|
|
Use ```` ```text ```` for plain output (e.g. error messages) and ```` ```python ````
|
|
for Python.
|
|
|
|
### Call-outs — use admonitions, not bold "Note:"
|
|
|
|
Instead of `**Note:** …`, use a [colon-fence admonition](https://myst-parser.readthedocs.io/en/latest/syntax/admonitions.html):
|
|
|
|
```md
|
|
:::{note}
|
|
Jungfraujoch currently only accepts `uint32` TIFF mask files.
|
|
:::
|
|
```
|
|
|
|
Available types include `note`, `tip`, `important`, `warning`, `caution`, `danger`.
|
|
|
|
### Links and cross-references
|
|
|
|
- **To another page in this documentation**, link by its label, not by file path:
|
|
|
|
```md
|
|
See {ref}`the data analysis guide <user.saxs.data_analysis>`.
|
|
```
|
|
|
|
- **External links** use ordinary Markdown: `[pyFAI](https://pyfai.readthedocs.io)`.
|
|
- **Downloadable files** (PDFs, etc.) must use the `{download}` role — a plain link
|
|
to a non-image file is *not* copied into the build and will 404:
|
|
|
|
```md
|
|
- {download}`SAXS standards plate (PDF) <SAXS_standards_plate.pdf>`
|
|
```
|
|
|
|
- **Images** use the `{figure}` directive (or standard ``); place the
|
|
image file next to the page that uses it:
|
|
|
|
````md
|
|
```{figure} omny_shuttle.png
|
|
The OMNY sample shuttle.
|
|
```
|
|
````
|
|
|
|
### Adding a new page
|
|
|
|
1. Create `docs/<section>/<name>.md` with a label and H1 as above.
|
|
2. Add it to the parent section's `{toctree}` so it appears in the navigation, e.g.
|
|
in `docs/user/saxs/saxs.md`:
|
|
|
|
````md
|
|
```{toctree}
|
|
---
|
|
maxdepth: 2
|
|
hidden: true
|
|
---
|
|
|
|
data_analysis
|
|
<name>
|
|
```
|
|
````
|
|
|
|
List entries by file name **without** the `.md` extension.
|
|
|
|
## Preview locally
|
|
|
|
```bash
|
|
cd docs
|
|
pip install -r requirements.txt # plus `pip install .` from the repo root for the API reference
|
|
make html
|
|
```
|
|
|
|
Open `docs/_build/html/index.html` in a browser.
|
|
|
|
## Pitfalls
|
|
|
|
- **Broken cross-references are warnings, not errors.** The build still succeeds and
|
|
publishes, but the link won't work. Check the Read the Docs build log (or the local
|
|
`make html` output) for `WARNING` lines after editing.
|
|
- **Everything here is public.** The site is world-readable. Avoid credentials, license
|
|
keys, personal logins, and anything not meant for a general audience. Internal
|
|
hostnames and `/sls/...` paths are fine if you intend them to be public.
|
|
- **Placeholders.** Bracketed values such as `[p-group]` or `[ra-c-110]` are meant to be
|
|
substituted by the reader; keep them consistent across a page.
|