(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 `![alt](file.png)`); 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.