docs/developer/developer.md

@@ -1,3 +1,33 @@
 (developer)=
-# Developer 
+# Developer
+Information for developers and maintainers of the cSAXS beamline documentation and software.
 
+```{toctree}
+---
+maxdepth: 2
+hidden: true
+---
+
+editing_docs
+
+```
+
+
+***
+
+````{grid} 2
+:gutter: 5
+
+```{grid-item-card}
+:link: developer.editing_docs
+:link-type: ref
+:img-top: /assets/index_contribute.svg
+:text-align: center
+:class-item: index-card
+
+## Editing the documentation
+
+Conventions for writing these MyST/Sphinx docs and how changes go live on Read the Docs.
+```
+
+````

docs/developer/editing_docs.md

@@ -0,0 +1,143 @@
+(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.