docs: modernise the installation guide - #426
Merged
Merged
Conversation
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>
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 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 Lomandoes 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, anduv run --with lomanfora 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 ispydotplus, and it arriveswith Loman automatically. The old text named the
graphvizPyPI package, which is not adependency at all. Replaced with a per-platform table, a
dot -Vcheck, and WindowsPATHguidance pointing at where current installers actually put the binary.Installing for development — a new section. Clone,
make install, done. It explainsthat the environment comes from Rhiza: the
Makefileis a thin shim forwarding to therhiza-taskCLI fetched throughuvx, andmake installalso runslocal-setup.sh, which installs Graphviz so the visualizationtests can run. Then
make test/fmt/all/help.Credit
The Graphviz sections are @nikjascrazzy's work from #378, resolved against the
## Optional extrassection 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.uv add loman,uv pip install loman,uv run --with loman,pip install loman,conda install -c conda-forge graphviz,make install,make help.interactive_widget,development/rhiza).lomanis absent from conda-forge (HTTP 404) and present on PyPI (200);graphvizison conda-forge (200) — so the conda advice is checked, not guessed.
installreally does depend onsetup, which is what makes theGraphviz claim in that section true.
release.md(
../../CHANGELOG.md, outsidedocs_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