Writing this documentation

The documentation is built with Sphinx. Its source is in docs/source and is published at https://casangi.github.io/cubevis/ 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. Beyond ordinary Markdown, three things are used here:

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.

```{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.

```{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:

visplot parameters · from the Python source: VisibilityPlotter

vis : str | None = None

Path to the data, MSv2 measurement set or MSv4 / Processing Set: the format is detected (on the kernel’s host when kernel_name is given). Exactly one of vis, ms or ps must be supplied.

autocorr : str = 'exclude'

Autocorrelations (baselines from an antenna to itself): "exclude" (default; cross-correlations only), "include" or "only". On VLBI data before amplitude calibration the autocorrelations are hundreds of times the cross-correlations and flatten every plot of all baselines. A baseline named in antenna ("BR&BR") is plotted whatever this says. Also the “Autocorrelations” switch in the Data section.

and for a task in the CASA layout:

iclean parameters · from the Python source: _iclean

kernel_name = None

Jupyter kernel to run tclean and the image access on

more
default: None; everything runs in this Python.
With a kernel name, tclean runs and the images are
read and written on the kernel's computer, and only
the window runs here.  vis and imagename are then
paths on that computer, relative to the kernel's
working directory, and this computer needs no CASA.
Kernels are set up with: python -m cubevis.setup
example: kernel_name='cvpost106-iclean'
niter = 0

Maximum number of iterations.

more
A stopping criterion based on total iteration count.
Currently the parameter type is defined as an integer therefore the integer value
larger than 2147483647 will not be set properly as it causes an overflow.

Iterations are typically defined as the selecting one flux component
and partially subtracting it out from the residual image.

niter=0 : Do only the initial major cycle (make dirty image, psf, pb, etc).

niter larger than zero : Run major and minor cycles.

Note : Global stopping criteria vs major-cycle triggers.

           In addition to global stopping criteria, the following rules are
           used to determine when to terminate a set of minor cycle iterations
           and trigger major cycles [derived from Cotton-Schwab Clean, 1984].

           'cycleniter' : controls the maximum number of iterations per image
                               plane before triggering a major cycle.
           'cyclethreshold' : Automatically computed threshold related to the
                                       max sidelobe level of the PSF and peak residual.
            Divergence, detected as an increase of 10% in peak residual from the
            minimum so far (during minor cycle iterations).

            The first criterion to be satisfied takes precedence.

Note :  Iteration counts for cubes or multi-field images :
            For images with multiple planes (or image fields) on which the
            deconvolver operates in sequence, iterations are counted across
            all planes (or image fields). The iteration count is compared with
            'niter' only after all channels/planes/fields have completed their
            minor cycles and exited either due to 'cycleniter' or 'cyclethreshold'.
            Therefore, the actual number of iterations reported in the logger
            can sometimes be larger than the user specified value in 'niter'.
            For example, with niter=100, cycleniter=20,nchan=10,threshold=0,
            a total of 200 iterations will be done in the first set of minor cycles
            before the total is compared with niter=100 and it exits.

 Note : Additional global stopping criteria include:
           - no change in peak residual across two major cycles.
           - a 50% or more increase in peak residual across one major cycle.

Slide decks

Each folder in devel/slides that contains a slides.html is copied to the site as <folder>/slides.html and listed on the Slide decks 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 (The visplot window, Help in the window). The code names each entry by a label, a target in visplot controls, in full or anywhere else, such as

(vp-flag-reach)=

### Flag reaches

and the build writes help/<label>.html for every label starting with vp-, a page that forwards to wherever the label is (docs/source/extensions/vp_help.py). So:

  • A label can go anywhere in the documentation, on any page, before a heading or before a paragraph, list or note inside a section. So the entry can be the place that already explains the control (a capability page, say) rather than a copy of it on the help page; two labels above one heading are fine. Each label is defined once.

  • Moving an entry, to another heading or another page, needs no change to the code: keep its label.

  • A new entry the code points at needs its label here in the same pull request. tests/manual/visplot/test_help_labels.py (run with the quick tests) fails for a label the code uses and the documentation does not define.

  • Do not remove or rename a label within a major.minor version. A later patch release replaces that version’s copy of the documentation, and the earlier patch releases still installed would lose the entry. To rename one, keep the old label as a second target above the heading.

A message gets a ⓘ by including help_text.marker("vp-…") in its text; a control’s description by giving its help spec a label ((text, "vp-…")).

A copy without the label (a release made before it, or a development version, which has no copy of its own and uses the latest) is sent to the latest copy’s entry by the site’s 404.html. To try ? against a local build, set CUBEVIS_DOCS_URL to it before starting visplot, for example CUBEVIS_DOCS_URL=http://localhost:8000/ with python -m http.server 8000 running in docs/build/html. Or push the change to a docs-<name> branch and set CUBEVIS_DOCS_URL to its preview copy, https://casangi.github.io/cubevis/dev/docs-<name>/, to try it before it is merged.

Building locally

$ pip install -r docs/requirements.txt
$ cd docs
$ make html
$ open build/html/index.html

The Python source is parsed, not imported, so cubevis and its dependencies do not need to be installed to build the documentation.

Publishing

The workflow in .github/workflows/docs.yml builds the site whenever the documentation, the slides, scripts/sync_layers or a documented source file changes. When a task from another source file is documented, add that file to the two paths lists in the workflow.

Several copies of the documentation are published side by side, all reachable from the Version menu under the sidebar title:

Copy

Address

Made by

latest

https://casangi.github.io/cubevis/

every documentation change on main

a release

https://casangi.github.io/cubevis/v1.2/

the first v1.2.x tag; later v1.2.x tags replace it

a preview

https://casangi.github.io/cubevis/dev/docs-<name>/

creating or pushing to a docs-<name> branch

Releases are kept per major and minor version only: v1.2.0, v1.2.1, … all publish to v1.2/, so the 1.2 documentation is that of the newest 1.2 release (set CUBEVIS_DOCS_PATCH_UPDATES to "0" in the workflow to keep the copy the first 1.2 tag made instead). Releases and previews show a banner pointing to the latest copy; previews are hidden from search engines.

To show documentation changes to other people before they are merged, work on a branch named docs-<something>. Its preview appears under dev/ a minute or two after the branch is pushed, is rebuilt on each push, and is removed when the branch is deleted. On a pull request the site is also built and attached to the workflow run as the docs-site artifact.

The published site lives on the gh-pages branch, which docs/publish_site.py rewrites as a single commit each time; it is never edited by hand.