Documentation

Documentation#

Estimated reading time: 26 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

説明

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

説明

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.

Render#

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

Table 8: Render Tasks#

Make Task

説明

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

説明

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

説明

ci-docs

The ci-docs.yml Action executes sphinx.ext.doctest to test doctest-style and code-output-style blocks within the documentation.

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.

Also see the make build tasks for further details.

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.

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.

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

ヒント

To support accessibility best practice use the :alt: option for both image and figure directives.

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

Pixi Task

説明

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.

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

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

$ pixi run tests-doc

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.

注釈

Failed image tests are captured via the pytest-pyvista plugin option --failed_image_dir within the test_images_failed directory for analysis and investigation.

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:

  • 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 12: Content Tags#

Category

Topic

説明

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.

注釈

Experimental features may be tagged with experimental 🧪

On this page