Documentation#
Estimated reading time: 33 minutes
Here we provide some high-level guidelines and best practice advice for authors and contributors wishing to build and render the documentation.
Building#
Reference:
docs/Makefiledocs/src/conf.py
The documentation is built using sphinx to parse and render reStructuredText
(rst) documents into HTML.
We also use myst-parser, a sphinx and docutils extension to parse and convert
MyST to rst, and myst-nb to execute and convert
Jupyter Notebooks into sphinx documents.
The documentation is built using sphinx-build and the GNU make tool from within
the docs root directory e.g.,
$ cd docs
$ make <make-task>
The following sections describe the make command tasks that are available.
Hygiene#
Start afresh with confidence by performing documentation hygiene to purge various build artifacts.
Make Task |
Description |
|---|---|
clean |
Purge all sphinx-autoapi, sphinx-gallery, sphinx-tags, carousel, and other sphinx-build artifacts. |
clean-all |
Perform both the clean and clean-cache tasks. |
clean-cache |
Purge the myst-nb Jupyter cache. See myst-nb configuration for further details. |
Build#
Build the documentation along with various controls to limit image creation. Note that building the documentation static images and interactive scenes can be resource hungry and time consuming.
Make Task |
Description |
|---|---|
html |
Build the full suite of documentation including all images and scenes. |
html-docstring |
Build the full suite of documentation with only the |
html-docstring-inline |
Build the full suite of documentation with only the |
html-gallery |
Build the full suite of documentation with only the sphinx-gallery images and scenes, which also includes the carousel. |
html-inline |
Build the full suite of documentation with only inline documentation images and scenes. |
html-noplot |
Build the full suite of documentation with no static images and no interactive scenes. |
html-tutorial |
Build the full suite of documentation with only the tutorial notebooks. images and scenes. |
Gallery#
Reference:
docs/src/_ext/gallery_scenes.pydocs/src/_ext/scene_footprint.pydocs/src/conf.py
The sphinx-gallery examples run in parallel, with up to four worker processes and never more than the available CPUs. sphinx-gallery runs the examples of one sub-gallery at a time, and most sub-galleries hold four examples or fewer, so more workers would use more memory without making the build any faster.
Set the GEOVISTA_SPHX_GLR_SERIAL environment variable to run the examples one at a time in the main process, e.g., when debugging an example.
Attention
Each worker is a new process, so it inherits the environment but not any
state set within the build process. That is why conf.py exports
PYVISTA_OFF_SCREEN and PYVISTA_PLOT_THEME as well as setting them
in-process. A worker that renders on-screen opens a window under
xvfb-run and waits on it until the build times out, as happened on
Read the Docs, which calls sphinx-build directly rather than through
the Makefile. A worker without the theme renders its examples with
the default geovista theme instead of geovista_document.
Most gallery examples show an interactive 3D scene, which pyvista exports
as a .vtksz file while building the gallery. Exporting a scene costs about
ten seconds of build time per 100 MB, and readers download the whole scene when
they open the page. The examples named in STATIC within
docs/src/_ext/gallery_scenes.py show a static image instead, and skip
the export altogether. Add an example there when its scene is large and adds
little over the image, and use the name the image tests use, e.g.,
grid.reykjanes_contour. A unit test rejects a name that matches no example.
The change also applies to an incremental build, which runs again each example
that has been added to or removed from STATIC since the last build.
Once the build has finished, docs/src/_ext/scene_footprint.py rewrites
every .vtksz scene it exported, gallery and docstring plots alike. The
exporter writes a texture as raw pixels and every point as float64, so each
scene with the base layer’s 7,020 x 3,510 texture carried about 39 MB of it,
and a full build came to 1.7 GB, over the 1,024 MB that Read the Docs allows
for the HTML of a build. The extension resamples a texture wider than
MAX_WIDTH, 2,048 pixels, to that width, and stores points as float32, which
took the scenes from 1,693 MB to 535 MB. A static image keeps the full
texture, since only the exported scene is rewritten.
Parallel Build#
Reference:
.readthedocs.ymldocs/src/_ext/parallel_build.py
Read the Docs runs sphinx-build with --jobs, so it reads the pages in
parallel, with one process for each available CPU. Most of a full build outside
the gallery is spent reading, as that is when the docstring and inline plots
render and the tutorial notebook runs. The Makefile targets still read
the pages one at a time.
Reading in parallel needs more memory, and some extensions build different
documentation in parallel. The parallel_build extension makes up for
each of them:
sphinx-gallery keeps its idle worker processes, and their memory, for five minutes after running the examples. Beside the processes reading the pages and the kernel running the tutorial notebook, that was more than Read the Docs allows, so the workers are stopped before the pages are read.
sphinx-tippycollects the tooltips of a page as it writes the page, so a page written by a worker process would lose them. The pages are written one at a time instead, which costs little, while still being read in parallel.sphinx.ext.viewcodewould render the source of a third-party module that a re-exported object resolves to, such aspooch.core, and would link the source of a module back to its objects by whichever module the merged reads reached first. Linking each module back by its own name also fixes the links ofgeovista.themes, which a serial build gets wrong.sphinx-llms-txtwould list some pages in the order in which the parallel reads are merged, rather than the sorted order of a serial build.
tests/docs/test_parallel_build.py builds a small project in parallel,
with and without the extension. Once a test of the build without it fails,
the upstream behaviour has changed and that part of the extension can go.
Attention
An extension that declares itself safe for parallel reading and writing may
still change the documentation in a parallel build, without a warning. Before
adding an extension, compare the files and contents of a build with
--jobs 2 against those of a serial build.
Render#
How-to serve the rendered documentation for inspection in a local browser.
Make Task |
Description |
|---|---|
serve-html |
Start a local |
Test#
Perform documentation quality assurance.
Make Task |
Description |
|---|---|
doctest |
Execute sphinx.ext.doctest to test code snippets within the documentation. |
Branding#
Reference:
docs/src/_staticdocs/src/conf.py
Our icons are provided by Font Awesome. Font Awesome (Free) is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).
Static icon assets are located in the docs/src/_static/images/icons directory,
along with the Font Awesome LICENSE.txt file. Refer to the docs/src/conf.py
for asset configuration details.
Other branding assets are available from the geovista-media repository.
Branding colours (RGB) are defined in docs/src/_static/color.css:
#80d050(128,208,80) is the primary colour (gv-text-main)#7f2faf(127,47,175) is the complementary colour (gv-text-comp)
Badge#
Reference:
docs/assets/badge/v0.json
Our shields.io badge asset is encoded as a JSON Endpoint Response.
The badge logo is based on the public domain Earth Grid Symbol SVG Vector, which is freely available and distributed under a CC0-1.0 licence.
<a href="https://geovista.readthedocs.io/en/latest/" >
<img alt="geovista-badge" src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/bjlittle/geovista/main/docs/assets/badge/v0.json" />
</a>
[](https://geovista.readthedocs.io/en/latest/)
.. |geovista-badge| image:: https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/bjlittle/geovista/main/docs/assets/badge/v0.json
:target: https://geovista.readthedocs.io/en/latest/
Logo#
Reference:
docs/src/_static/brand/geovista-logo.svg
Fig. 5: GeoVista Logo#
The geovista logo takes its inspiration from The Great Wave off Kanagawa
(c. 1830-1832) by Katsushika Hokusai, the influential Japanese ukiyo-e
woodblock print artist. The logo palette is primarily sampled from the painting,
and also includes all four classical elements of earth (),
water (), air (), and fire (),
reflecting the theme of nature woven throughout the geovista documentation.
Logo Font#
Reference:
docs/src/_static/brand/geovista-title.svgdocs/src/_static/fonts/la-machine-company.ttf
The geovista logo title is rendered using the La Machine Company TrueType font.
Fig. 6: GeoVista Logo Title#
Continuous Integration#
Reference:
.github/workflows
The following documentation workflows are available:
Workflow |
Description |
|---|---|
The ci-docs.yml Action executes
sphinx.ext.doctest to test doctest-style and code-output-style blocks
within the documentation, for the latest SPEC 0 supported distribution
of Also see the documentation Pixi Workflow doctest task. |
|
The ci-tests-docs.yml Action builds the documentation using the
Also see the make build tasks for further details. |
|
The ci-inventories.yml Also see the documentation Pixi Workflow fetch-inventories task. |
|
The .readthedocs.yml workflow builds and publishes our documentation on the ReadtheDocs (RTD) platform. See the Versions section for each Refer to the Builds section for a render of the documentation for each
|
Note
Our documentation workflows build against the latest SPEC 0 supported
distribution of python alone, whereas the
testing workflows
cover every one of them. A single distribution is enough to show that the
documentation toolchain works, and the latest is where a documentation
dependency, or the chromium build that the
Browser Tests require, first falls behind.
tests/test_python_support.py holds the ci-docs.yml and
ci-tests-docs.yml matrices to this, so a SPEC 0 bump that misses either
of them fails.
Copyright & License#
Reference:
LICENSEpyproject.toml
Source code must contain the following copyright and license preamble at the top of the file:
# Copyright (c) 2021, GeoVista Contributors.
#
# This file is part of GeoVista and is distributed under the 3-Clause BSD license.
# See the LICENSE file in the package root directory for licensing details.
Quality assurance of preamble compliance is provided by the ruff preview rule
CPY001 (flake8-copyright).
Configuration of this single preview rule is defined in the pyproject.toml manifest.
For further details refer to the following TOML tables:
[tool.ruff.lint][tool.ruff.lint.flake8-copyright][tool.ruff.lint.per-file-ignores]
Title Style#
Hand-authored page and section titles use Chicago Manual of Style headline style, with one deviation, the same rule as the tephpy title style:
Capitalize the first and last words, all major words, and prepositions of four letters or more.
Lowercase articles, coordinating conjunctions, the infinitive “to”, and prepositions of three letters or fewer.
The deviation is the length threshold. The Chicago Manual of Style lowercases a
preposition however long it is, whereas geovista capitalizes the longer ones, as
in “Where geovista Departs From pyvista”, while keeping the short ones down, as in
“What Changes in transform_mesh”. Both parts of a hyphenated compound are
capitalized, as in “Reading-Time Banner”.
Keep the literal case of code and API identifiers, filenames, paths and commands;
of project names, such as geovista, pyvista and pixi; and of acronyms
and scientific symbols. The rule applies to page titles, section titles, rubrics,
card titles, table titles, table column headers and link text that names a section.
It does not apply to generated API pages, numpydoc section headers, changelog
entries, or anything that is a full sentence, such as captions and admonition text,
which use sentence case.
Cross-References#
Reference:
docs/src/common.txt
Arbitrary locations are cross-referenced using reStructuredText labels and the sphinx
:ref:
role.
For consistency, the following structure is recommended for our labels:
A label should be prefixed with
gv-to indicate inclusion within thegeovistanamespace.The
gv-prefix should then be followed by the name of the file containing the label, with hyphens replacing spaces and special characters, and all characters in lower case e.g.,gv-next-stepsfor thedocs/src/next_steps.rstdocument. Include the sub-directory structure in the label if the file is not in thedocs/srcdirectory, e.g.,gv-developer-towncrierfor thedocs/src/developer/towncrier.rstdocument.If appropriate, the label should then be followed by the title of the section or subsection it’s referencing, with hyphens replacing spaces and special characters, and all characters in lower case e.g.,
gv-developer-documentation-cross-referencesfor the Cross-References section in thisdocs/src/developer/documentation.rstdocument. If the label doesn’t proceed a section or subsection title, then use a suitable description that is concise and uniquely identifies the location within the document. Avoid using abbreviations or acronyms unless strictly necessary.
Tip
A label prefixed with tippy-gv- instead of gv- will have a
sphinx-tippy tooltip rendered for each of its cross-reference links e.g.,
hover over this
Cross-References tooltip enabled link
A top-level label must be present on the first line of a document.
An include directive may be used on the first line of a document providing convenient access to common project references e.g.,
.. include:: common.txt
Where the common.txt file is located in the docs/src directory.
Otherwise, the top-level label must follow the include directive e.g., the
docs/src/developer/documentation.rst document has the following preamble:
.. include:: ../common.txt
.. _gv-developer-documentation:
.. _tippy-gv-developer-documentation:
:fa:`square-pen` Documentation
==============================
To cross-reference a figure or a table use the :name: option to
create the label, ensuring to append its title (or similar) for uniqueness e.g.,
the docs/src/overview.rst document has the following
figure within
its Ecosystem section:
.. figure:: _static/images/ecosystem.png
:align: center
:alt: GeoVista Ecosystem
:name: tippy-gv-overview-ecosystem-geovista-ecosystem
Ecosystem of ``geovista``
Hint
To support accessibility best practice use the :alt: option for both
image and figure directives.
Intersphinx#
Reference:
.github/scripts/inventories.pydocs/src/_inventorydocs/src/conf.py
Cross-references into the documentation of another project are resolved by
intersphinx, which downloads an inventory of targets from each project in
the INTERSPHINX_URLS mapping of docs/src/conf.py.
Since geovista builds its documentation in nitpicky mode with
--fail-on-warning, every one of those projects would otherwise be a hard
build dependency: a site that is briefly unavailable fails the build, both for
the inventory it could not download and for each cross-reference that
inventory would have resolved.
To avoid this, a copy of each inventory is vendored in the
docs/src/_inventory directory and offered to intersphinx as a
fallback location. A build always prefers the remote inventory, so it carries
the current targets; the vendored copy is consulted only when the remote cannot
be reached, and sphinx does not warn when a later location succeeds.
Important
Adding a project to INTERSPHINX_URLS must be accompanied by its
vendored inventory. Refresh them with:
$ pixi run -e docs fetch-inventories
Then commit whichever *.inv files have changed. The
ci-inventories.yml workflow runs the same task monthly and raises a
pull-request when an inventory has moved on.
Should every location for an inventory fail, say for a project added without a
vendored fallback, the intersphinx_resilience extension disables
nitpicky mode for the remainder of the build, reporting the failure without
failing on it. The documentation is then built, but unresolved cross-references
go unreported, so treat a degraded build as a warning to refresh the
inventories rather than a pass.
Tooltips#
Reference:
docs/src/_static/jsdocs/src/conf.pytests/docs/test_tooltips.py
A sphinx-tippy tooltip previews the target of a link without following it.
Which links are given one is settled twice over, by two conf.py settings
that behave quite differently:
Setting |
Description |
|---|---|
|
Regular expressions matched against the |
|
Class names consulted in the browser as the tooltip is attached. A link skipped here still has a tooltip generated for it, and merely never has one shown. |
Attention
A tippy_skip_urls pattern is applied with re.match against the
href exactly as it was written into the page, which is bare between
sibling pages (clouds.html) and directory-prefixed from anywhere else
(../generated/gallery/domain/clouds.html). A pattern for one shape
silently misses the other, so conf.py generates both, anchored at
the end so that a deliberate tippy-gv- fragment may still opt its target
back in.
Attention
tippy_skip_anchor_classes replaces the extension defaults of
headerlink and sd-stretched-link rather than extending them, so both
must be restated alongside any addition. Dropping sd-stretched-link is
what allows a sphinx-design card to raise a tooltip carrying the heading
and opening paragraph of the page that it links to, since such a card is an
anchor stretched over the whole card body.
Tooltips are skipped for the sphinx-gallery thumbnails, which render a tooltip of their own that a second one would collide with, and for the sphinx-tags badges, whose tooltip repeats the text of the badge that raised it.
The tippy.js and popper runtime bundles are vendored in the
docs/src/_static/js directory, since the extension otherwise loads them
from a third-party CDN on every page, leaving a reader with no tooltips at
all when that host cannot be reached.
See also
The tests/docs/test_tooltips.py unit tests hold all of the above in
place, inspecting the built payload of each page for the static behaviour
and driving a browser for the rest. See
Browser Tests for further details.
Sphinx Directives#
Reference:
docs/src/_extdocs/src/conf.py
The following custom sphinx reStructuredText (rst) directives
are available to documentation authors.
readingtime#
Usage:
.. readingtime:: [<duration>|<wpm>]
Calculates an estimated reading time of an entire page based on the number of words and a default words-per-minute reading heuristic for technical documents.
The words are counted on the parsed page rather than in its source, so directive names, option lines, link targets, comments and substitution definitions do not inflate the estimate, and a body generated by another directive is included in it. A substitution is counted where it expands, once per use.
The default rate is 150 words-per-minute. Brysbaert [Bry19] puts
most adults between 175 and 300 words-per-minute on English
non-fiction, averaging 238; these pages are pitched below that band
because they alternate prose with code and output that a reader works through
line by line.
Accepts an optional <duration> reading time (in minutes), a literal
reading time to be quoted rather than calculated. Reach for it on a page whose
estimate is wrong for a reason the word count cannot see, such as a tutorial
whose reader stops to run every snippet. On a page the count gets right it is
a figure that has to be revised by hand every time the page changes.
The directive then creates a branded readingtime banner in-situ e.g.,
.. readingtime:: 5
Generates the banner:
Estimated reading time: 5 minutes
Alternatively, provide an optional words-per-minute to override the directive default when calculating the reading time estimation e.g.,
.. readingtime:: 1000wpm
Generates the following banner, using 1,000 words-per-minute to calculate
the estimate to read this Documentation page:
Estimated reading time: 5 minutes
Note
A default words-per-minute value will always be used to generate a reading
time for a directive with no arguments i.e., .. readingtime::.
Warning
Any other argument fails the build. Quietly falling back on the default would publish an estimate the author never asked for, and nothing would say that the argument had been misspelled.
Every page a reader reads start to finish opens with a banner, placed at column zero after the title and before the first section heading. A page carries exactly one. The two live examples above sit well below the first heading of this page, which is what makes them demonstrations and not banners.
A page that is navigated rather than read carries none: the site root and the section landing pages, the reference pages whose body a directive generates, the release notes, the lookup tables ( Glossary, Key Bindings, Environment Variables and About), and Changelog, whose body is an include of a page that carries the banner already. Putting a duration on a glossary invites a reader to treat it as a chapter.
Important
Those pages are named in EXEMPT in
tests/docs/test_readingtime_coverage.py, each with the reason
beside it, and the gate there holds every other page to the rule. It
derives the pages it governs from docs/src rather than listing
them, so a new page is covered from the day it lands. Adding one means
adding the banner or adding the reason.
Theme#
Reference:
docs/src/_staticdocs/src/conf.pytests/docs
The documentation is rendered with sphinx-book-theme, which is layered upon
pydata-sphinx-theme. Note that sphinx-book-theme pins pydata-sphinx-theme
to an exact version, so the pair of them only ever move together.
Attention
docs/src/_static/sidebar_toggle.js is a workaround, not a feature.
sphinx-book-theme renders a second primary and secondary sidebar toggle and
hides the pydata-sphinx-theme pair, yet both themes bind their handlers to
the first match i.e., the hidden one. That leaves the visible buttons inert
and both sidebars unreachable on a narrow viewport. The shim forwards clicks to
the bound button of each pair, and self-retires once only one button remains.
It also closes the primary dialog at (min-width: 992px), since the
dialog inherits the classes of the sidebar, and therefore its wide-viewport
collapsed state, which would otherwise strand the dialog open but invisible over
a page that it blocks.
The two halves retire on different schedules, so re-check both on every theme bump.
The theme chrome is assembled in the browser and so is beyond the reach of the
Image Tests, which compare pyvista scenes
rather than page furniture. It is instead covered by the
Browser Tests, which exercise both sidebars
either side of the 992 pixel theme breakpoint, and across a resize through it.
Pixi Workflow#
Reference:
pyproject.toml
Pixi Environment
Documentation pixi tasks are available in the
docs, geovista and py3xx variant of
those pixi environments e.g., geovista-py313. See
Packaging for further details.
The documentation may be built and rendered using
pixi run tasks, all of
which do not require to be executed from within the docs root directory, unlike
the above Building make command tasks e.g.,
$ pixi run <pixi-task>
Pixi Task |
Description |
|---|---|
clean |
Purge all sphinx-autoapi, sphinx-gallery, sphinx-tags, carousel, and other sphinx-build artifacts. |
clean-all |
Perform both the clean and clean-cache tasks. |
clean-cache |
Purge the myst-nb Jupyter cache. See myst-nb configuration for further details. |
doctest |
Execute sphinx.ext.doctest to test code snippets within the documentation. Note that the clean task is called prior to running this task. |
fetch-inventories |
Refresh the vendored intersphinx fallback inventories in the
|
make |
Build the documentation using Note that the clean task is called prior to running this task. |
serve-html |
Build the documentation using Note that the clean and make tasks are called prior to running this task. |
tests-docs |
Perform documentation image tests of $ pixi run tests-docs
This task calls Note that the tests-clean, download and make tasks are called prior to running this task. See Packaging for further details. This task is only available in the geovista and geovista-py3xx environments. Note Failed image tests are captured via the |
tests-docs-browser |
Perform browser tests of the documentation theme chrome e.g., $ pixi run tests-docs-browser
This task calls Accepts a documentation build target as an optional argument, which is
built first. Defaults to $ pixi run tests-docs-browser html-gallery
A non-empty second argument passes $ pixi run tests-docs-browser html-noplot "" 0
Note that the make task is called prior to running this task. This task is only available in the geovista and geovista-py3xx environments. See Testing for further details. Attention The default |
tests-docs-browser-install |
Install the $ pixi run tests-docs-browser-install
This is a one-off, as playwright manages the browser separately from
its This task is only available in the geovista and geovista-py3xx environments. |
Tip
Apply the --frozen option to avoid pixi checking and updating the pixi.lock file.
E.g., To only build the Gallery examples and serve the rendered documentation:
$ pixi run --frozen serve-html html-gallery
Tagging#
Reference:
docs/src/conf.py
Themed content Tags are supported using sphinx-tags.
Tags provide a simple and intuitive way to group and filter content, improving discoverability and browsing. This allows users to easily explore or quickly find related topics and content.
Gallery Examples must contain one or more content
tags using the tags directive to highlight noteworthy topics demonstrated
within the example e.g.,
.. tags::
component: manifold, filter: contour
A tag consists of a lower-case category: topic pair, where:
categoryis a domain area of interest,topicis a specific subject within that domain, anda colon (
:) separates each of the above tag components
Single word tags are preferred. However, consider using a hyphen (-) to
separate a multi-word category or topic within a tag e.g.,
data-type: point-cloud.
Endeavour to group tags of the same category on the same line, ordered
alphabetically by topic. Note that multiple tags must be separated by a
comma (,).
Tags may span multiple contiguous lines, ordered alphabetically by category
e.g.,
.. tags::
component: coastlines, component: manifold, component: texture,
filter: threshold,
render: camera, render: subplots,
sample: unstructured,
style: opacity
Category |
Topic |
Description |
|---|---|---|
component |
|
Content that demonstrates the use of a specific feature. |
domain |
|
Content that is relevant to a specific scientific domain or discipline. |
filter |
|
Content that demonstrates the use of specific filtering techniques. |
load |
|
Demonstrates use of the |
plot |
|
Content that showcases various plotting techniques. |
projection |
|
Content that demonstrates the use of geospatial projections or transformations. |
resolution |
|
Content using high-resolution or high-volume geospatial data. |
sample |
|
Content that leverages the convenience of
pre-canned geospatial sample data available
from the |
style |
|
Content that includes customization of various render styles and aesthetics. |
widget |
|
Content that demonstrates the use of interactive widgets. |
Note
Experimental features may be tagged with experimental 🧪
References#
M. Brysbaert. How many words do we read per minute? A review and meta-analysis of reading rate. Journal of Memory and Language, 109:104047, December 2019. URL: https://doi.org/10.1016/j.jml.2019.104047, doi:10.1016/j.jml.2019.104047.