Repository navigation
Conversation
The docs explain why NCBI and GTDB are combined, how to install omataxonomy, how to build the database (including the choice of GTDB release and building from a prepared archive) and walk through the query API in an annotated tutorial. An API reference is generated from the docstrings, two of which needed a blank line before their field lists to render. The examples in background.md and tutorial.md are run as doctests against the pinned GTDB r232 test database, so they cannot drift from the actual output. The docs are built with sphinx, myst-parser and furo from a new "docs" dependency group, limited to Python >= 3.11 so that the test matrix down to Python 3.9 is unaffected. .readthedocs.yaml installs that group with uv.
There was a problem hiding this comment.
🟡 Changes recommended
Documented workflows fail as written, and several guarantees contradict the implementation.
7 open findings
What changed in this PR
Adds a Sphinx documentation site for omataxonomy, covering its combined taxonomy, database setup, and query API.
Changes:
- Adds guides, an annotated tutorial, and generated API documentation.
- Configures Read the Docs and Python ≥3.11 documentation dependencies.
- Adds documentation doctests and fixes docstring formatting.
| File | Description |
|---|---|
uv.lock |
Locks documentation dependencies. |
tests/test_doctests.py |
Tests background and tutorial examples. |
pyproject.toml |
Adds documentation dependencies and project links. |
omataxonomy/query.py |
Adds blank lines for docstring rendering. |
docs/tutorial.md |
Demonstrates taxonomy queries and tree annotation. |
docs/installation.md |
Documents installation and prerequisites. |
docs/index.md |
Introduces the package and documentation navigation. |
docs/database.md |
Explains database creation and management. |
docs/conf.py |
Configures Sphinx, extensions, and theme. |
docs/background.md |
Explains combining NCBI and GTDB. |
docs/api.md |
Generates the public API reference. |
.readthedocs.yaml |
Configures hosted documentation builds. |
🧠 Review effort: Balanced
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
+19
to
+20
| 1. downloads the current NCBI taxdump (`taxdump.tar.gz`) and checks it | ||
| against its md5 checksum, |
Comment on lines
+108
to
+110
| from omataxonomy import build_combined_tarball | ||
|
|
||
| build_combined_tarball("omatax-gtdb-r232.tar.gz", gtdb_release=232) |
Comment on lines
+116
to
+117
| tax = Taxonomy(dbfile="/data/taxonomy/gtdb-r232/taxonomy.sqlite", | ||
| taxdump_file="omatax-gtdb-r232.tar.gz") |
| column is the code and its second column a taxid or a scientific name: | ||
|
|
||
| ```python | ||
| tax.update_mnemonic_codes(speclist="speclist.txt", extra_file="extra_codes.tsv") |
- build_combined_tarball changes into a temporary directory before
writing the archive, so a relative target ended up in that directory
and was deleted with it. update_db failed on a bare archive file name
because os.makedirs('') raises. Both now resolve their paths first.
- the md5 checksum of the NCBI taxdump was only compared for an already
existing file, never after downloading it. A mismatch after the
download now raises an IOError.
- update_mnemonic_codes(speclist=...) passed the value to urlretrieve,
which rejects plain file paths, so a local speclist.txt was never
loaded. Existing files are now read directly.
- GTDB taxids are reproducible for a given release, but a taxon can get a different taxid in another release if hash collisions change. Say so instead of promising stable taxids. - mention that building from an archive still downloads the UniProt mnemonics and how to load them offline. - tax2track of annotate_tree only covers the taxids already in the tree, not the inferred ancestors.
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 docs explain why NCBI and GTDB are combined, how to install
omataxonomy, how to build the database (including the choice of GTDB
release and building from a prepared archive) and walk through the
query API in an annotated tutorial. An API reference is generated from
the docstrings, two of which needed a blank line before their field
lists to render.
The examples in background.md and tutorial.md are run as doctests
against the pinned GTDB r232 test database, so they cannot drift from
the actual output.
The docs are built with sphinx, myst-parser and furo from a new "docs"
dependency group, limited to Python >= 3.11 so that the test matrix
down to Python 3.9 is unaffected. .readthedocs.yaml installs that group
with uv.