docs: rewrite the home, installation and quickstart pages - #12
Merged
Merged
Conversation
The landing pages kept the pre-Furo content (generic cards, a raw file tree). Home: SPDNet pipeline diagram with the shape at each layer, a reading path, an "I want to... / read" table, what the library does differently, a diagram of the three package levels and the neighbouring repositories, a module table linked to the reference. Installation: a "which install" table, pinning, GPU builds, development and documentation builds, troubleshooting of the common errors. Quickstart: links to the guides. Two new diagrams (make_diagrams.py). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQdVCDbXCd8gvf1Y4TufJR
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PQdVCDbXCd8gvf1Y4TufJR
There was a problem hiding this comment.
Copilot review overview
🟡 Changes recommended
Documentation inaccuracies and a missing diagram-generation dependency remain unresolved.
Review effort: Lite
Findings: 1
Open (6)
What changed in this PR
Rewrites the home, installation, and quickstart documentation with improved navigation, setup guidance, and generated diagrams.
Changes:
- Adds pipeline, package-level, and navigation diagrams.
- Expands installation, GPU, development, and troubleshooting guidance.
- Adds quickstart links and deterministic diagram generation.
| File | Summary |
|---|---|
docs/quickstart.md |
Adds onward-reading guide links. |
docs/installation.md |
Expands installation and development instructions. |
docs/index.md |
Reworks the landing page and package overview. |
docs/_static/diagrams/spdnet_pipeline.svg |
Adds the SPDNet pipeline diagram. |
docs/_static/diagrams/retractions.svg |
Regenerates diagram output. |
docs/_static/diagrams/reeig.svg |
Regenerates diagram output. |
docs/_static/diagrams/parametrization.svg |
Regenerates diagram output. |
docs/_static/diagrams/package_levels.svg |
Adds the package-level diagram. |
docs/_static/diagrams/implicit_diff.svg |
Regenerates diagram output. |
docs/_static/diagrams/daleckii_krein.svg |
Regenerates diagram output. |
docs/_static/diagrams/bw_fold.svg |
Regenerates diagram output. |
docs/_static/diagrams/batchnorm_steps.svg |
Regenerates diagram output. |
docs/_diagrams/make_diagrams.py |
Adds diagram generation and stable SVG output. |
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| ```bash | ||
| pip install -e ".[docs]" | ||
| make -C docs html # docs/_build/html/index.html | ||
| python docs/_diagrams/make_diagrams.py # only after changing a diagram |
| | `functions` | `spd_linalg`: matrix functions, congruences, vectorizations | {doc}`reference/spd_linalg` | | ||
| | | `spd_geometries.*`: the six geometries | {doc}`reference/geometries` | | ||
| | | `m_estimators`: sample covariance, Tyler, Student-t | {doc}`reference/m_estimators` | | ||
| | | `scalar_functions`, `stiefel`, `random` | {doc}`reference/utilities` | |
Comment on lines
+21
to
+22
| `main` is the latest released state. Pin a tag or a commit for reproducible | ||
| experiments: `...yetanotherspdnet.git@<tag-or-sha>`. In a `pyproject.toml`: |
Comment on lines
+63
to
+64
| Every layer and function takes `device` and `dtype`, so a model moves to the | ||
| GPU like any PyTorch model. For matrices of a few hundred rows, a CPU run with |
| ```bash | ||
| pytest # full suite, coverage enforced (>= 40 %) | ||
| pytest tests/nn/test_base.py::TestBiMap --no-cov # one class, without coverage | ||
| ruff format . && ruff check . # what the CI lint job runs |
Comment on lines
+103
to
+104
| The online documentation is built from `main` by the `Documentation` | ||
| workflow, at each release or on demand (`gh workflow run docs.yml --ref main`). |
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 landing pages still had their pre-Furo content: generic cards and a raw file tree on the home page, a bare list on the installation page.
Changes
docs/_diagrams/make_diagrams.py.sphinx-build -Wpasses with no warnings;ruff format --checkandruff checkare clean.