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

  • docs/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.

Table 6: Housekeeping Tasks#

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.

Table 7: Build Tasks#

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 docstring images and scenes.

html-docstring-inline

Build the full suite of documentation with only the docstring and inline images and scenes. See html-docstring and html-inline tasks.

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.

Parallel Build#

Reference:

  • .readthedocs.yml

  • docs/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-tippy collects 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.viewcode would render the source of a third-party module that a re-exported object resolves to, such as pooch.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 of geovista.themes, which a serial build gets wrong.

  • sphinx-llms-txt would 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.

Render#

How-to serve the rendered documentation for inspection in a local browser.

Table 8: Render Tasks#

Make Task

Description

serve-html

Start a local HTTP server on port 11000 to view the rendered documentation. This is necessary in order to support interactive scenes.

Test#

Perform documentation quality assurance.

Table 9: Test Tasks#

Make Task

Description

doctest

Execute sphinx.ext.doctest to test code snippets within the documentation.

Branding#

Reference:

  • docs/src/_static

  • docs/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.

geovista-badge

<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>
[![geovista-badge](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/bjlittle/geovista/main/docs/assets/badge/v0.json)](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 Font#

Reference:

  • docs/src/_static/brand/geovista-title.svg

  • docs/src/_static/fonts/la-machine-company.ttf

The geovista logo title is rendered using the La Machine Company TrueType font.

GeoVista Logo Title

Fig. 6: GeoVista Logo Title#

Continuous Integration#

Reference:

  • .github/workflows

The following documentation workflows are available:

Table 10: Documentation Workflows#

Workflow

Description

ci-docs

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 python.

Also see the documentation Pixi Workflow doctest task.

ci-images

The ci-tests-docs.yml Action builds the documentation using the make command task html-docstring-inline and then performs image testing of pyvista-plot directive static scenes, for the latest SPEC 0 supported distribution of python.

Also see the make build tasks for further details.

ci-inv

The ci-inventories.yml cron based Action monthly refreshes the vendored intersphinx fallback inventories, raising a pull-request when any of them has moved on.

Also see the documentation Pixi Workflow fetch-inventories task.

ci-rtd

The .readthedocs.yml workflow builds and publishes our documentation on the ReadtheDocs (RTD) platform.

See the Versions section for each tag release of the documentation hosted on RTD along with the latest render of the main branch, and a stable render of the latest tag release.

Refer to the Builds section for a render of the documentation for each pull-request.

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 the geovista namespace.

  • 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-steps for the docs/src/next_steps.rst document. Include the sub-directory structure in the label if the file is not in the docs/src directory, e.g., gv-developer-towncrier for the docs/src/developer/towncrier.rst document.

  • 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-references for the Cross-References section in this docs/src/developer/documentation.rst document. 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.

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

Intersphinx#

Reference:

  • .github/scripts/inventories.py

  • docs/src/_inventory

  • docs/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.

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

  • docs/src/conf.py

  • tests/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:

Table 11: Tooltip Skip Settings#

Setting

Description

tippy_skip_urls

Regular expressions matched against the href of a link as the tooltip is generated. A link skipped here has no tooltip in the payload of the page at all.

tippy_skip_anchor_classes

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.

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.

Sphinx Directives#

Reference:

  • docs/src/_ext

  • docs/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

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.

Theme#

Reference:

  • docs/src/_static

  • docs/src/conf.py

  • tests/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.

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>
Table 12: Pixi Tasks#

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 docs/src/_inventory directory. See Intersphinx.

make

Build the documentation using html-noplot by default. Pass either html, html-docstring, html-docstring-inline, html-gallery, html-inline or html-tutorial as an argument to override the default html-noplot behaviour.

Note that the clean task is called prior to running this task.

serve-html

Build the documentation using html-noplot by default and start a local HTTP server on port 11000 to view the rendered documentation. This is necessary in order to support interactive scenes. Pass either html, html-docstring, html-docstring-inline, html-gallery, html-inline or html-tutorial as an argument to override the default html-noplot behaviour.

Note that the clean and make tasks are called prior to running this task.

tests-docs

Perform documentation image tests of pyvista-plot directive static scenes e.g.,

$ pixi run tests-docs

This task calls pytest --doc_mode to perform the documentation image tests using the pytest-pyvista plugin. Refer to the [tool.pytest.ini_options] table entry in the pyproject.toml manifest for default configuration options.

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.

tests-docs-browser

Perform browser tests of the documentation theme chrome e.g.,

$ pixi run tests-docs-browser

This task calls pytest tests/docs to drive a headless chromium browser over the built documentation using playwright.

Accepts a documentation build target as an optional argument, which is built first. Defaults to html-noplot e.g.,

$ pixi run tests-docs-browser html-gallery

A non-empty second argument passes --browser-strict, which fails rather than skips a test whose prerequisite is missing. The tests run in parallel, one worker per CPU core, each launching its own browser over the one build. The optional third argument is the number of workers, where 0 runs them serially in a single process e.g.,

$ 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.

tests-docs-browser-install

Install the chromium browser required by the tests-docs-browser task e.g.,

$ pixi run tests-docs-browser-install

This is a one-off, as playwright manages the browser separately from its python bindings.

This task is only available in the geovista and geovista-py3xx environments.

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:

  • category is a domain area of interest,

  • topic is a specific subject within that domain, and

  • a 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
Table 13: Content Tags#

Category

Topic

Description

component

coastlines, graticule, manifold, texture, vectors

Content that demonstrates the use of a specific feature.

domain

meteorology, oceanography, orography, seismology, volcanology

Content that is relevant to a specific scientific domain or discipline.

filter

cast, contour, extrude, glyph, threshold, triangulate, warp

Content that demonstrates the use of specific filtering techniques.

load

curvilinear, geotiff, grid, points, rectilinear, unstructured, vectors

Demonstrates use of the geovista.bridge to load various types of geospatial data.

plot

anti-aliasing, camera, log-scale subplots

Content that showcases various plotting techniques.

projection

crs, transform

Content that demonstrates the use of geospatial projections or transformations.

resolution

high

Content using high-resolution or high-volume geospatial data.

sample

curvilinear, geotiff, grid, points, rectilinear, unstructured, vectors

Content that leverages the convenience of pre-canned geospatial sample data available from the geovista.pantry.

style

colormap, lighting, opacity, shading

Content that includes customization of various render styles and aesthetics.

widget

checkbox, logo, north-arrow

Content that demonstrates the use of interactive widgets.

References#

[Bry19]

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.