Repository navigation
docs: update the docs for the build coordinator - #683
Merged
Merged
Conversation
This was referenced Nov 5, 2026
karhu
force-pushed
the
tnet-157/22-docs
branch
2 times, most recently
from
November 5, 2026 20:07
8b69f9a to
e489bd0
Compare
karhu
force-pushed
the
tnet-157/22-docs
branch
from
November 6, 2026 07:54
e489bd0 to
52b9a6a
Compare
The API pages took the last part of the module path as their name, and only a clash, such as timenet.sources and timenet_connectors.sources, gave a page its full path. So most names did not show the package, and a new module could rename the pages of an old one. scripts/gen_api_docs.py now names every page by its full dotted path, for example api/timenet.client.md. It needs no clash check, because two modules never share a dotted path. The commit regenerates the nav in zensical.toml and updates the links to the API pages in client.md, connectors.md, manifest.md, registry.md, timef-dataset.md, timef-reader.md and types.md. Part of TNET-157.
The later rounds of the stack changed rules that the docs describe. This commit adds them to the docs: - The order of a sources list is the read order. A release that two sources hold is read from the first one, so the local registry goes first to read offline (client.md, build.md, registry.md, the timenet-datasets skill). - Without a version, the first source that serves the dataset gives its newest version. Only @latest reads the highest version of all sources. The docs said that no version means latest (client.md, registry.md, cli/timenet.md, data-model/datasets.md, the skill). - timenet.build() takes the default list with the local registry first. It refuses a remote or read-only local_registry, and it takes force= and open_access_only=. publish() takes a DatasetRef too (build.md). - Registries take read_only=True and then refuse each write with TimeNetRegistryError (registry.md). - copy_release() and download() copy the payload sources that the manifest lists, not the parents. with_payload_sources=False copies the release alone (registry.md, client.md, cli/build.md). - A registry flag that names no registry exits with code 2 (cli/build.md). - The cache checks run before a clear deletes and before a build removes its raw downloads, not when the settings load (the skill). - A download adds its copy to the local registry, not to the cache (timef-format.md). The build diagram names the local registry, not the store (architecture.md). Part of TNET-157.
The docs pass added prose lines over 100 columns. AGENTS.md asks for prose near 100 columns. This commit rewraps each such line, through the end of its paragraph, with the words unchanged. A code span stays on one line. It also fixes the typo "dependet on" in docs/cli/timenet.md and in the same sentence of the timenet-datasets skill. Part of TNET-157.
Before a build, a release has no lineage. timenet info now says so in the access row of a card that declares parents. The page on access levels names this case. Part of TNET-157.
BaseRegistry.search() takes a DatasetFilter in place of the filter keywords. The search section of the registry page shows the filter, DatasetFilter.of() and the error for a negative limit. The examples that ask one registry pass a DatasetFilter. The registry page names has_catalog of the S3 backend. Part of TNET-157.
The record now stores its kind as "kind": "download" or "build", and LocalRegistry.read_origin() reads it. The page of the local registry shows the new record and the method. Part of TNET-157.
TimeNetNotBuiltError holds the card of the connector. The example of the client page reads error.card in place of a second call of get_card(), and the dataset skill names the attribute. Part of TNET-157.
The manifest guide says that a build needs the parents and that a read needs only the payload sources. It now names Manifest.required_releases(), which lists these releases. Part of TNET-157.
The provenance record now says "kind": "download" for a copy from a registry. The skill of the datasets still said that the record of a download says copy. Part of TNET-157.
BaseRegistry.search() now sorts the catalog by dataset ID before it filters, and TimeNet.search() gives each source the limit. The search section of the registry guide says that the search returns the first matches by dataset ID, and that a task or time_series_spec filter stops to read manifests at the limit. Part of TNET-157.
timenet download takes --force. It copies the release again, as download(force=True) does. Part of TNET-157.
A provenance record that is not valid raises TimeNetOriginError, which names its first problem. Its hint names the forced download and the forced build, which replace the release and its record. The client guide, the error table and the page of the timenet CLI say so. Part of TNET-157.
BaseRegistry.location is abstract now, so no registry gives its name in place of a location. Part of TNET-157.
The error table names TimeNetUnreachableError, the difference and the registry_location of TimeNetVersionConflictError, and the path of TimeNetManifestError. Part of TNET-157.
TimeNet.plan_read() left the public API, because Plan stays internal. The method table and the list of methods that take version= in docs/client.md, and the timenet-datasets skill, no longer name it. Part of TNET-157.
The docs named the last stage store, after a BaseConnector.store() method that does not exist. The engine writes the dataset with timenet.engine.store_dataset(), so the pipeline diagrams, the tables and the connector skill name that function. Part of TNET-157.
The README example imported timenet without using it. In the tables of docs/cli/timenet.md and the timenet-datasets skill, GitHub split a cell at the bar of URL|PATH, so these cells say URL or PATH. Part of TNET-157.
TimeNet.search() now filters the merged rows of list(). The search section of docs/registry.md describes DatasetFilter.select() and ListedRelease: select() checks the card first, reads the schema of a matching card from its registry, and stops at limit matches. A row without a registry never matches a task or time_series_spec filter. docs/client.md and the timenet-datasets skill say that search() checks the highest version of each dataset only, and that it reads a manifest only for a row whose card matches. Part of TNET-157.
TimeNet.list() and TimeNet.search() now leave a source without a catalog out with a CatalogWarning. If no source has a catalog, they raise TimeNetNoCatalogError, whose hint names the read of an exact release. docs/registry.md, docs/client.md and the timenet-datasets skill say this. docs/types.md adds the error to its table and the warning to its warnings, and says that both warnings point at the first line outside the timenet package. Part of TNET-157.
A clear of the local registry now checks for symlinked dataset and release folders also when every kind goes. So a symlinked folder stops timenet local clear too, before it deletes anything. docs/cli/timenet.md and the timenet-datasets skill say this. Part of TNET-157.
TimeNet.search() and timenet search filter the merged rows of list(). So they check only the highest version of each dataset, and they do not find an older version that matches. The search section of the registry guide, the browse section of the client guide and the search row of the CLI guide now say so. Part of TNET-157.
timenet list and timenet search leave out a source without a catalog and a connector card that cannot be read. For each, they print a warning line to stderr, without a Python file and line number. The CLI guide now says so. Part of TNET-157.
Every command of both CLIs now has the same help for --local-registry: the local registry, where downloads and builds land and which a lookup checks first. The guides of timenet and timenet-build build and the timenet-datasets skill use this text. Part of TNET-157.
…lict The info commands of timenet local now give a provenance record that is not valid the same hint as the clear commands. Before the build, timenet-build build --publish-to names --force when the destination and the local registry hold two different releases under the version. ReleaseDifference comes from timenet.types.references. The CLI guides and the error table say so. Part of TNET-157.
ReleaseDifference moved back into timenet.errors, next to TimeNetVersionConflictError, whose difference attribute has this type. The row of the error in the types page now names that module. Part of TNET-157.
- put_dataset refuses a version when the registry lacks one of its payload sources, not one of its parents. - A source's resolve() takes a Version object, or None for the newest version of that source. - get_manifest() raises TimeNetManifestError for a stored manifest that is not valid. - Only the registries, auto-build, isolation, the cache and the token have environment variables. The build guide links to the settings table. - The build steps describe the order of the default list of sources. A Python build with its own list uses that order instead. - read_only=True belongs to the local registry in the list, not to the client. - The timenet-datasets skill names the three source flags and links to the CLI docs for the details, instead of repeating that section. Part of TNET-157.
karhu
force-pushed
the
tnet-157/22-docs
branch
from
November 10, 2026 17:41
f139a17 to
04830ed
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The Stack
This stack covers refactoring the internal logic of how releases are resolved during read, download & build, in particular also in the context of parent releases / parent datasets. On top of that it refactors the public TimeNet APIs and CLI interfaces around these actions, to streamline the behavior across them.
This PR
This PR holds every doc change of the stack: the user docs, the CLI pages, the agent skills and the READMEs. The PRs below it change no
.mdfile.Details
--helpof its command, andmake docsbuilds without a warning.Design decisions
api/timenet.client.md. So a new module with the same short name cannot rename a page.scripts/gen_api_docs.py, the nav in zensical.toml and the links use the new names.Breaking changes
api/client.mdbecomesapi/timenet.client.md. Links to the old pages break.Stack
Changes later in the stack:
Merge message