166 lines
4.9 KiB
Markdown
166 lines
4.9 KiB
Markdown
# 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
|
|
|
|
```
|
|
|
|
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.
|