riverarchitect.guide

The Live Guide: a worked example that runs on the bundled sample data.

River Architect’s modules chain together - a lifespan map needs a detrended DEM and a depth-to-water-table raster, and those have to be built first. Reading that in the documentation is one thing; doing it is another, and the step people get stuck on is the first one, because a condition that is not prepared produces either an error or, worse, an empty map that looks like an answer.

This module holds that walkthrough as data: an ordered tuple of GuideStep, each naming the tab it belongs to, the settings to enter and what the result should look like. Both front ends render the same tuple, so the guide cannot say one thing in the Qt window and another in the tkinter one, and a test can check that the tabs it names exist.

The reach is 2100_sample, a real gravel-cobble reach in U.S. customary units that ships in sample-data/ of a source clone. sample_data_dir() finds it; activate_sample_data() points the project home at it.

class riverarchitect.guide.GuideStep(key, title, group, tab, body, settings=(), expect='', writes=())

Bases: object

One step of the walkthrough.

Parameters:

• key (str) – short identifier, for tests and for deep links.

• title (str) – heading, e.g. "2. Lifespan mapping".

• group (str) – the top-level tab the step happens in, as TAB_GROUPS names it.

• tab (str) – the module tab within that group. Equal to group for a lone tab.

• body (str) – the explanation, as paragraphs separated by a blank line.

• settings (tuple) – (label, value) pairs to enter in the tab.

• expect (str) – what the result should look like, so a reader can tell it worked.

• writes (tuple) – the files the step produces, relative to the project directory.

paragraphs()

The body split into paragraphs, for a renderer that lays them out itself.

riverarchitect.guide.TITLE = 'Live Guide: Example'

Title of the guide, shown in the Help menu and as the window title.

riverarchitect.guide.CONDITION = '2100_sample'

The condition the guide works on.

riverarchitect.guide.DOCS_URL = 'https://riverarchitect.readthedocs.io/'

Where the full documentation lives.

riverarchitect.guide.sample_data_dir()

Locate the bundled sample-data directory, or return None.

It ships in a source clone, not in a wheel, so an installed copy of River Architect normally has no sample data and the guide says so rather than failing.

riverarchitect.guide.activate_sample_data()

Point the project home at the bundled sample data.

Returns:

the directory now in use.

Return type:

str

Raises:

FileNotFoundError – when no bundled sample data can be found.

riverarchitect.guide.sample_data_status()

One line describing whether the guide can run, and against what.

Returns:

(ready, message).

Return type:

tuple

riverarchitect.guide.as_text(steps=None, width=88)

Render the guide as plain text, for a terminal or a log.

Parameters:

• steps (tuple) – the steps to render. Defaults to STEPS.

• width (int) – wrap width.

Returns:

the whole guide.

Return type:

str