# Editing the documentation

This site is built with [Zensical](https://zensical.org/) and hosted on
[Read the Docs](https://sls-csaxs.readthedocs.io). 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:

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

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

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

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

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

### Callouts

Use an admonition with its contents indented by four spaces:

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

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

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

````markdown
=== "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:

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

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