csaxs_bec/docs/developer/editing_docs.md

(developer.editing_docs)=

Editing the documentation

This documentation is built with Sphinx using the MyST Markdown parser, and hosted on Read the Docs. 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:

(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:

```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:

:::{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:

  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:

  - {download}`SAXS standards plate (PDF) <SAXS_standards_plate.pdf>`
  

• Images use the {figure} directive (or standard ![alt](file.png)); place the image file next to the page that uses it:

  ```{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:

   ```{toctree}
   ---
   maxdepth: 2
   hidden: true
   ---
   
   data_analysis
   <name>
   ```
   

   List entries by file name without the .md extension.

Preview locally

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.