# Writing this documentation
The documentation is built with [Sphinx](https://www.sphinx-doc.org). Its
source is in [`docs/source`](https://github.com/casangi/cubevis/tree/main/docs/source)
and is published at by a GitHub
Actions workflow.
## Editing a page
Pages are Markdown (`.md`) files. New pages should be Markdown; the older
reStructuredText (`.rst`) pages build alongside them and can be converted
when convenient.
To add a page, create the `.md` file and add its name (without the
extension) to a `toctree` list, for example the *User guide* list in
`index.md`.
The Markdown dialect is [MyST](https://myst-parser.readthedocs.io). Beyond
ordinary Markdown, three things are used here:
````markdown
A link to another page, by file name: [](remote_kernels.md)
:::{note}
A highlighted note. Also: warning, tip.
:::
```{figure} _static/window.png
:alt: the visplot window
:width: 100%
A figure with a caption.
```
````
## Including text from the Python source
Parameter descriptions are written once, in the docstring of the class
that implements a task. The CASA task and CASA shell layers are generated
from that docstring by `scripts/sync_layers`, and the documentation
includes it with the same scraper. To change what a parameter's
description says, change the docstring.
````markdown
```{task-doc} visplot
```
````
inserts the description at the top of the task's docstring. With
`:section: Resource lifecycle` it inserts that section of the docstring
instead.
````markdown
```{task-params} visplot
:only: vis, ms, ps
```
````
inserts parameters with their types, defaults and full descriptions.
| Option | Effect |
|---|---|
| (none) | every parameter, in the order of the signature |
| `:only: a, b, c` | these parameters, in this order |
| `:exclude: a, b` | every parameter but these |
| `:all:` | every parameter not already shown by another `task-params` block on the same page |
The name after the directive is a task name or class name from
`scripts/sync_layers/project_layers.yaml`. Parameters listed there as
`layer_args` are supplied by the layers themselves and are never shown.
Two docstring layouts are understood:
- **numpy style**, as in `visplot`: a `Parameters` heading underlined with
dashes. The descriptions are reStructuredText.
- **the CASA task layout**, as in `iclean`, whose task is generated from
`tclean`'s XML: a `--------- parameter descriptions ---------` block.
The descriptions are preformatted text, so the first line is shown and
the rest is behind a **more** control.
A task generated by `sync_layers` (an entry under `templates` in the YAML
file) is available to the directives without further configuration. A
task generated another way is added to the `documentation` list at the
end of that file, as `iclean` is, naming the file, class and method to
read.
On GitHub, where the directives are not expanded, each appears as a small
code block marking where the text will go.
Included text is drawn in a bordered, tinted box that names the class it
came from. This is how it looks:
```{task-params} visplot
:only: vis, autocorr
```
and for a task in the CASA layout:
```{task-params} iclean
:only: kernel_name, niter
```
## Slide decks
Each folder in `devel/slides` that contains a `slides.html` is copied to
the site as `/slides.html` and listed on the [](slides.md) page.
Adding a deck needs no change to the documentation.
## visplot's in-window help
In the `visplot` window, text in the status area that has a longer
explanation here carries a ⓘ, and pressing **?** opens this
documentation at that explanation ([](applications/visplot.rst), *Help in
the window*). The code names each entry by a label, a target in
[](applications/visplot_help.md) or anywhere else, such as
```markdown
(vp-flag-reach)=
### Flag reaches
```
and the build writes `help/