csaxs_bec/docs/developer/editing_docs.md

Editing the documentation

This site is built with Zensical and hosted on Read the Docs. Pages live in docs/; zensical.toml at the repository root controls navigation and rendering.

How a change goes live

• In the browser. Open a page in Gitea and click Edit to propose a change through a branch and pull request (or a personal fork if required).

• Locally. Create a branch, edit the Markdown pages, push, and open a pull request.

A documentation maintainer reviews and merges the pull request into main. The .gitea/workflows/rtd_deploy.yml action then triggers a Read the Docs build of latest. The .readthedocs.yaml configuration installs the documentation requirements, builds the site, and copies it to Read the Docs' HTML output directory.

Preview locally

On Linux or macOS, run these commands from the repository root:

python -m venv .venv-docs
source .venv-docs/bin/activate
python -m pip install -e '.[docs]'
zensical serve

Open the local URL printed by Zensical. The preview reloads automatically after edits; stop it with ++ctrl+c++.

To generate the static site:

zensical build --clean

Output is written to site/.

The docs extra in pyproject.toml installs Zensical and PyMdown Extensions alongside the repository's regular dependencies. Read the Docs uses the same editable installation command. Do not commit the generated site/ directory. The API reference is currently omitted.

Anatomy of a page

Start with one H1 heading:

# Setup online radial integration on Jungfraujoch

Headings receive native Zensical anchors automatically. Use these anchors for section links, or link directly to the Markdown file when referring to a whole page. Copy a heading's permalink in the preview to get its anchor.

For an explicit, stable anchor, attach an ID directly to the heading:

## Online integration { #online-integration }

Reference it with [Online integration](page.md#online-integration). Use heading anchors rather than separate HTML <a> tags.

Conventions

Lists and tables

Leave a blank line before a list or table that follows a paragraph. Indent paragraphs, nested lists, callouts, and code blocks inside a list item by four spaces. These rules keep procedures numbered continuously and prevent tables and list markers from appearing as plain text.

Code blocks

Tag fenced code blocks with python, bash, or text so highlighting and copy buttons work:

```bash
module load Python/3.11.11
pip install "pyFAI[gui]"
```

Callouts

Use an admonition with its contents indented by four spaces:

!!! note
    Jungfraujoch currently only accepts `uint32` TIFF mask files.

Use note, tip, warning, or danger; a custom title follows the type:

!!! danger "In an emergency"
    Call 3333.

Keyboard shortcuts and tabs

Use ++ctrl+c++ for ++ctrl+c++ and ++tab++ for ++tab++. Use content tabs for alternative workflows, such as previewing or building the site:

=== "Preview"

    ```bash
    zensical serve
    ```

=== "Build"

    ```bash
    zensical build --clean
    ```

Keep required procedure steps and warnings outside tabs so readers see them regardless of which alternative they select.

Links, downloads, and images

Link to Markdown source paths relative to the current page. Zensical rewrites them to the generated HTML URLs. For example, from this page:

[Online integration](../user/saxs/online_integration.md)
[Angle files](../user/ptychography/flomni.md#angles-from-a-file-tomo_type-4)
[Safety checklist (PDF)](../assets/safety-at-csaxs.pdf)

PDFs and other assets under docs/ are copied automatically. Place images next to the page that uses them and use ordinary Markdown:

![The OMNY sample shuttle](omny_shuttle.png)

Use [label](https://example.org) for external links. Put placeholder values such as <position> inside backticks so they are displayed as text.

Adding a page

1. Create docs/<section>/<name>.md with an H1.
2. Add the page to project.nav in zensical.toml.
3. Add a link from the relevant section overview where useful.
4. Build and check the resulting page and its links.

The docs/plans/ directory contains working implementation plans and is excluded from the published site. The P-touch implementation plan is also excluded from publication. Navigation entries alone do not exclude other pages from publication.

Before opening a pull request

• Check the build output.
• Click through changed links; a successful build alone does not prove every external link works.
• Confirm that callouts, images, tables, and downloads render correctly.

The documentation is public. Keep credentials, license keys, and private personal information out of pages and downloadable files.