Skip to content

docs: modernise the installation guide - #426

Merged
HarryCampion merged 1 commit into
masterfrom
docs/modernise-install-guide
Sep 7, 2026
Merged

docs: modernise the installation guide#426
HarryCampion merged 1 commit into
masterfrom
docs/modernise-install-guide

Conversation

@HarryCampion

Copy link
Copy Markdown
Collaborator

The installation page still recommended Anaconda as the way to install Loman, and told
readers to run python install graphviz — not a command — to get a Python library Loman
does not use. It made no mention of uv, of the Python versions Loman actually
supports, or of how to set the project up to work on.

What it says now

Requirements — Python 3.11+, tested on 3.11 through 3.14. The page never said.

Installing Loman — uv first (uv add, uv pip install, and uv run --with loman for
a throwaway environment), pip alongside it, and conda covered honestly: Loman is published
on PyPI and not on conda-forge, so inside a conda environment the answer is still pip.
Graphviz is on conda-forge, which is why conda still earns a mention.

Optional extras — kept from #411, with the install line shown in both uv and pip form.

Graphviz — Loman shells out to dot; the Python glue is pydotplus, and it arrives
with Loman automatically. The old text named the graphviz PyPI package, which is not a
dependency at all. Replaced with a per-platform table, a dot -V check, and Windows
PATH guidance pointing at where current installers actually put the binary.

Installing for development — a new section. Clone, make install, done. It explains
that the environment comes from Rhiza: the
Makefile is a thin shim forwarding to the rhiza-task CLI fetched through uvx, and
make install also runs local-setup.sh, which installs Graphviz so the visualization
tests can run. Then make test / fmt / all / help.

Credit

The Graphviz sections are @nikjascrazzy's work from #378, resolved against the
## Optional extras section that landed in #411 after that PR was opened (which is why
#378 now shows a conflict), with a conda-forge row added. They are credited as
co-author on the commit. #378 is superseded by this rather than rejected — happy to
reverse that if they would rather land theirs first.

Verified rather than assumed

  • tests/test_docs.py — 7 passed.
  • The built page contains each command as rendered text — uv add loman,
    uv pip install loman, uv run --with loman, pip install loman,
    conda install -c conda-forge graphviz, make install, make help.
  • Both relative links resolve (interactive_widget, development/rhiza).
  • loman is absent from conda-forge (HTTP 404) and present on PyPI (200); graphviz is
    on conda-forge (200) — so the conda advice is checked, not guessed.
  • rhiza-task's install really does depend on setup, which is what makes the
    Graphviz claim in that section true.
  • The build's single remaining warning is the pre-existing one in release.md
    (../../CHANGELOG.md, outside docs_dir), untouched here.

Related

The README's Development section has its own inaccuracies — it advertises make check,
which is not a target, and calls the task runner "Taskfile". Out of scope here; worth a
follow-up.

🤖 Generated with Claude Code

The page still recommended Anaconda as the way to install Loman, and told
readers to run `python install graphviz` -- not a command -- to get a Python
library Loman does not use. It made no mention of uv, of the Python versions
Loman actually supports, or of how to set the project up to work on.

Rewritten around what is true now:

- **Requirements.** Python 3.11+, tested on 3.11 through 3.14. The page never
  said.
- **uv first**, with `uv add`, `uv pip install` and `uv run --with loman` for a
  throwaway environment; pip kept alongside it, conda covered honestly (Loman is
  on PyPI and not conda-forge, so inside a conda env the answer is still pip).
- **Graphviz.** Loman shells out to `dot`; the Python glue is `pydotplus` and it
  arrives with Loman. The old text named the `graphviz` PyPI package, which is
  not a dependency, and gave Anaconda-era Windows paths. Now a per-platform
  table, a `dot -V` check, and Windows PATH guidance that matches where current
  installers put the binary.
- **Development.** New section: clone, `make install`, and the fact that the
  environment comes from Rhiza -- the Makefile is a shim forwarding to
  rhiza-task, fetched through uvx, and `make install` also runs local-setup.sh,
  which installs Graphviz so the visualization tests can run.

The Graphviz sections are @nikjascrazzy's work from #378, resolved against the
`## Optional extras` section that landed in #411 after that PR was opened, with
conda-forge added as a row. #378 is superseded rather than rejected.

Verified: tests/test_docs.py passes (7); the built page contains each command
as rendered text; both relative links resolve; the build's single warning is
the pre-existing one in release.md, untouched here. Checked rather than
assumed: loman is absent from conda-forge (404) and present on PyPI, graphviz
is on conda-forge, and `install` really does depend on `setup`.

Co-authored-by: nikjascrazzy <nikjascrazzy@users.noreply.github.com>
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@HarryCampion
HarryCampion merged commit 7e56b3f into master Sep 7, 2026
52 checks passed
@HarryCampion
HarryCampion deleted the docs/modernise-install-guide branch September 7, 2026 00:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant