# 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/