From b5905eeaa792f621bc9da8d9a64ff42b2a11e0f1 Mon Sep 17 00:00:00 2001
From: Henry Schreiner <henryschreineriii@gmail.com>
Date: Mon, 5 Jun 2023 15:00:31 -0400
Subject: [PATCH] docs: filling out a bit more

Signed-off-by: Henry Schreiner <henryschreineriii@gmail.com>
---
 .github/CONTRIBUTING.md | 17 ++++++++++++-----
 docs/checks.md          |  6 +++---
 docs/cli.md             | 33 +++++++++++++++++++++++++++++++++
 docs/families.md        |  6 ++++++
 4 files changed, 54 insertions(+), 8 deletions(-)

diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 64a98ae..112015b 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -3,7 +3,7 @@ detailed description of best practices for developing Scikit-HEP packages.
 
 [scientific-python development pages]: https://learn.scientific-python.org/development
 
-# Quick development
+## Quick development
 
 The fastest way to start with development is to use nox. If you don't have nox,
 you can use `pipx run nox` to run it without installing, or `pipx install nox`.
@@ -26,7 +26,9 @@ $ nox -s build  # Make an SDist and wheel
 Nox handles everything for you, including setting up an temporary virtual
 environment for each run.
 
-# Setting up a development environment manually
+You can also use `nox -s run -- .` to run an example set of checks on a repo.
+
+## Setting up a development environment manually
 
 You can set up a development environment by running:
 
@@ -56,7 +58,7 @@ pre-commit install # Will install a pre-commit hook into the git repo
 
 You can also/alternatively run `pre-commit run` (changes only) or `pre-commit run --all-files` to check even without installing the hook.
 
-# Testing
+## Testing
 
 Use pytest to run the unit checks:
 
@@ -64,7 +66,7 @@ Use pytest to run the unit checks:
 pytest
 ```
 
-# Building docs
+## Building docs
 
 You can build the docs using:
 
@@ -78,7 +80,7 @@ You can see a preview with:
 nox -s docs -- serve
 ```
 
-# Pre-commit
+## Pre-commit
 
 This project uses pre-commit for all style checking. While you can run it with
 nox, this is such an important tool that it deserves to be installed on its
@@ -89,3 +91,8 @@ pre-commit run -a
 ```
 
 to check all files.
+
+## Running DevContainer
+
+You can use DevContainer, such as in GitHub Codespaces or locally. Nox and a
+local install will be available.
diff --git a/docs/checks.md b/docs/checks.md
index 364217b..dba162d 100644
--- a/docs/checks.md
+++ b/docs/checks.md
@@ -95,9 +95,9 @@ Here is the suggested function for the above example:
 
 ```python
 def repo_review_checks() -> dict[str, General | PyProject]:
-    return {p.__name__: p() for p in General.__subclasses__()} | {
-        p.__name__: p() for p in PyProject.__subclasses__()
-    }
+    general = {p.__name__: p() for p in General.__subclasses__()}
+    pyproject = {p.__name__: p() for p in PyProject.__subclasses__()}
+    return general | pyproject
 ```
 
 You tell repo review to use this function via an entry-point:
diff --git a/docs/cli.md b/docs/cli.md
index f0490fd..f66a543 100644
--- a/docs/cli.md
+++ b/docs/cli.md
@@ -1,5 +1,38 @@
 # CLI
 
+Repo-review has a CLI interface.
+
 ```{program-output} python -m repo_review --help
 
 ```
+
+There are three output formats; `rich` produces great terminal output, `html`
+produces an HTML report, and `json` produces a output that can be processed
+easily.
+
+JSON output looks like this:
+
+```json
+{
+  "families": {
+    "pyproject": {},
+    "general": {}
+  },
+  "checks": {
+    "PY001": {
+      "family": "general",
+      "description": "Has a pyproject.toml",
+      "result": true,
+      "err_msg": "",
+      "url": ""
+    },
+    "PY002": {
+      "family": "general",
+      "description": "Has a README.(md|rst) file",
+      "result": true,
+      "err_msg": "",
+      "url": ""
+    }
+  }
+}
+```
diff --git a/docs/families.md b/docs/families.md
index 4354754..3f875ba 100644
--- a/docs/families.md
+++ b/docs/families.md
@@ -34,3 +34,9 @@ families = "my_plugin_package.my_family_module:get_families"
 ```
 
 The entry-point name doesn't matter.
+
+```{admonition} Fixtures
+Unlike almost all other parts of the API, the family function does not support
+fixtures. This could be added if there is a need, but usually not needed - if a
+check is not present from a family, the family will not be displayed.
+```