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 |
|
these parameters, in this order |
|
every parameter but these |
|
every parameter not already shown by another |
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: aParametersheading underlined with dashes. The descriptions are reStructuredText.the CASA task layout, as in
iclean, whose task is generated fromtclean’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= NonePath to the data, MSv2 measurement set or MSv4 / Processing Set: the format is detected (on the kernel’s host when
kernel_nameis given). Exactly one ofvis,msorpsmust 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 inantenna("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= NoneJupyter 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= 0Maximum 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 |
every documentation change on |
|
a release |
|
the first |
a preview |
|
creating or pushing to a |
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.