cleaning up

Author: matomatical

CONTRIBUTING.md

@@ -4,6 +4,13 @@ Contributing to matthewplotlib
 Best to discuss before attempting to contribute. This file contains some notes
 to self.
 
+Development dependencies
+------------------------
+
+* uv for managing virtual environment
+* make for building docs, running tests, making releases
+* pandoc for building some parts of docs
+
 Workflow
 --------
 
@@ -14,16 +21,18 @@ To work on a new feature:
    * mypy checks pass (`mypy matthewplotlib/`).
    * Tests pass (`pytest tests/ -v`), including integration tests for all
      examples.
-   * Docs up to date (`make DOCS.md`).
-   * Road map (in README.md) is up to date.
-   * Change log (CHANGELOG.md) is up to date.
+   * Docs up to date (`make docs`).
+   * Roadmap (`pages/roadmap.md`) is up to date.
+   * Changelog (`CHANGELOG.md`) is up to date.
    * All new features are exported in `__init__.py`.
 3. Then merge into main
 
 Notes:
 
 * CHANGELOG entries should be concise and describe API-level changes, not
-  implementation details
+  implementation details.
+* Important notes on implementation should be documented in the code, or, if
+  there's no appropriate place for that, in commit notes or PR or something.
 
 Testing
 -------
@@ -57,3 +66,4 @@ To release a new version:
 8. Push: `git push origin main --tags`.
 9. On GitHub, create a new release from the tag.
 
+TODO: Make sure we also build docs for the new version.

README.md

@@ -1,8 +1,12 @@
-Matthew's plotting library (matthewplotlib)
-===========================================
+`matthewplotlib`: Matthew's plotting library
+============================================
 
 A Python plotting library that aspires to *not be painful.*
 
+```console
+pip install git+https://github.com/matomatical/matthewplotlib.git
+```
+
 *Status:* Work in progress. See [roadmap](https://matthewplotlib.far.in.net/roadmap.html). Currently,
 still generally painful, due to lack of generated documentation and lack of
 common plot types. However, for personal use, I'm already finding what limited
@@ -38,12 +42,6 @@ Rough edges:
 
 * API for compositions not final.
 * API for axes not final.
-* No labels available for bars/columns/histograms yet.
+* No axes/labels available for bars/columns/histograms yet.
 * Limited [documentation](https://matthewplotlib.far.in.net/).
 * Limited input validation, error handling.
-
-Install:
-
-```console
-pip install git+https://github.com/matomatical/matthewplotlib.git
-```

docs-research.md

@@ -138,7 +138,7 @@ More elaborate documentation:
 * [ ] Tutorials and recipes.
 * [ ] Freeze documentation with each version.
 * [x] Links to source code from within documentation.
-* [ ] Links to mentioned functions/classes/methods/types within documentation
+* [x] Links to mentioned functions/classes/methods/types within documentation
   (automatically linked to relevant release).
 * [x] Documentation search.
 

pages/roadmap.md

@@ -38,6 +38,8 @@ dev = [
   # testing
   "pytest",
   "pytest-cov",
+  # docs
+  "pdoc",
   # for examples (needed for integration tests)
   "scikit-learn",
   "psutil",