docs: migrate to zensical
This commit was merged in pull request #329.
This commit is contained in:
wakonig_k committed
1 parent
ca96f41a45
commit
bf8036b72d
34 files changed
+658
-1518
No files matched your search
+130
-108
@@ -1,143 +1,165 @@
|
||||
(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.
|
||||
:::
|
||||
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
|
||||
|
||||
There are two ways to propose an edit:
|
||||
- **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).
|
||||
|
||||
- **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.
|
||||
- **Locally.** Create a branch, edit the Markdown pages, 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.
|
||||
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.
|
||||
|
||||
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.
|
||||
## 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
|
||||
|
||||
Every content page starts with a **cross-reference label** followed by a single
|
||||
top-level heading:
|
||||
Start with one H1 heading:
|
||||
|
||||
```md
|
||||
(user.saxs.online_integration)=
|
||||
```markdown
|
||||
# Setup online radial integration on Jungfraujoch
|
||||
```
|
||||
|
||||
- The label `(user.saxs.online_integration)=` 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.
|
||||
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
|
||||
|
||||
### Code blocks — always tag the language
|
||||
### Lists and tables
|
||||
|
||||
Use a language on every fenced block so syntax highlighting and the copy button work:
|
||||
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.
|
||||
|
||||
````md
|
||||
### 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]"
|
||||
```
|
||||
````
|
||||
|
||||
Use ```` ```text ```` for plain output (e.g. error messages) and ```` ```python ````
|
||||
for Python.
|
||||
### Callouts
|
||||
|
||||
### Call-outs — use admonitions, not bold "Note:"
|
||||
Use an admonition with its contents indented by four spaces:
|
||||
|
||||
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.
|
||||
:::
|
||||
```markdown
|
||||
!!! note
|
||||
Jungfraujoch currently only accepts `uint32` TIFF mask files.
|
||||
```
|
||||
|
||||
Available types include `note`, `tip`, `important`, `warning`, `caution`, `danger`.
|
||||
Use `note`, `tip`, `warning`, or `danger`; a custom title follows the type:
|
||||
|
||||
### Links and cross-references
|
||||
|
||||
- **To another page in this documentation**, link by its label, not by file path:
|
||||
|
||||
```md
|
||||
See {ref}`the Jungfraujoch setup guide <user.saxs.online_integration>`.
|
||||
```
|
||||
|
||||
- **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 ``); 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
|
||||
---
|
||||
|
||||
online_integration
|
||||
<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
|
||||
```markdown
|
||||
!!! danger "In an emergency"
|
||||
Call 3333.
|
||||
```
|
||||
|
||||
Open `docs/_build/html/index.html` in a browser.
|
||||
### Keyboard shortcuts and tabs
|
||||
|
||||
## Pitfalls
|
||||
Use `++ctrl+c++` for ++ctrl+c++ and `++tab++` for ++tab++. Use content tabs for
|
||||
alternative workflows, such as previewing or building the site:
|
||||
|
||||
- **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.
|
||||
````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.
|
||||
Reference in new issue
Block a user