docs: some getting started info

docs/index.html

@@ -63,7 +63,7 @@
       root.render(
         <App
           header={true}
-          deps={["sp_repo_review==2023.06.01", "repo-review==0.7.0b4"]}
+          deps={["sp_repo_review==2023.06.01", "repo-review==0.7.0b5"]}
         />,
       );
     </script>

docs/index.md

@@ -4,7 +4,9 @@
 :maxdepth: 2
 :hidden:
 
+intro
 cli
+plugins
 fixtures
 checks
 families

docs/intro.md

@@ -0,0 +1,76 @@
+# Installing / Getting Started
+
+Repo-review is a framework for running checks from plugins. You need to have a
+plugin for repo-review to do anything. The examples below use `sp-repo-review`
+as an example. You can also use the WebAssembly version from web pages, [like
+the demo page](https://scientific-python.github.io/repo-review).
+
+## Installing
+
+`repo-review` (and presumably, most/all plugins) are available from pip. If you
+want to run a single plugin that depends on repo-review, then the easiest way
+to use it is:
+
+```bash
+pipx run sp-repo-review .
+```
+
+This uses [pipx][] (pip for executables) to download the plugin and all of it's
+dependencies (including repo-review itself) into a temporary virtual
+environment (cached for a week), then runs it.
+
+Any other way you like installing things works too, including `pipx install`
+and `pip install`.
+
+Plugins are also encouraged to support pre-commit and GitHub Actions.
+
+## Running checks
+
+You can run checks with (`pipx run`) `repo-review <path>` or `python -m
+repo_review <path>`. See [](cli) for command-line options.
+
+## Configuring
+
+You can explicitly list checks to select or skip in your `pyproject.toml`:
+
+```toml
+[tool.repo-review]
+select = [...]
+ignore = [...]
+```
+
+## Pre-commit
+
+You can also use this from pre-commit:
+
+```yaml
+- repo: https://github.com/scientific-python/repo-review
+  rev: <version>
+  hooks:
+    - id: repo-review
+      additional_dependencies: ["sp-repo-review==<version>"]
+```
+
+(Insert the current version above, and ideally pin the plugin version, as long
+as you have a way to auto-update it.)
+
+Though check your favorite plugin, which might directly support running from
+pre-commit, and then pre-commit's pinning system will pin on your plugin,
+rather than the framework (repo-review).
+
+## GitHub Actions
+
+```
+- uses: scientific-python/repo-review@<version>
+  with:
+    plugins: sp-repo-review
+```
+
+(Insert the current version above, optionally pin the plugin version, as long
+as you have a way to auto-update it.)
+
+Though check your favorite plugin, which might directly support running from
+GitHub Actions, and then Dependabot's updating system will pin on your plugin,
+rather than the framework (repo-review).
+
+[pipx]: https://pypa.github.io/pipx

docs/plugins.md

@@ -0,0 +1,84 @@
+# Writing a plugin
+
+To write a plugin for repo-review, you should provide one or more [](checks).
+You can also add new [](fixtures), and customize [](families) with sorting and
+nicer display names. When writing a plugin, you should also do a few things
+when setting up the package. These suggestions assume you are using a
+standardized backend, such as `hatchling`, `flit-core`, `pdm-backend`, or
+`setuptools>=61`. If you are using some other build backend, please adjust
+accordingly.
+
+## Custom entry-point (optional)
+
+If you want to provide your own CLI name, you can
+add this to your `pyproject.toml`:
+
+```toml
+[project.scripts]
+my_plugin_cli_name = "repo_review.__main__:main"
+```
+
+However, there is no benefit over just running `repo-review`, so this is not
+really recommended.
+
+## Pipx run support (recommended)
+
+If you chose not to add a custom command-line entry point (above), you should
+still support `pipx run <your-plugin>`, and you can do that by adding the
+following to your `pyproject.toml`:
+
+```toml
+[project.entry-points."pipx.run"]
+my_plugin_package_name = "repo_review.__main__:main"
+```
+
+## Pre-commit support
+
+You can add a `.pre-commit-hooks.yaml` file with contents similar to this to
+natively support pre-commit:
+
+```yaml
+id: repo-review
+name: repo-review
+description: Check for configuration best practices
+entry: repo-review
+language: python
+types_or: [text]
+minimum_pre_commit_version: 2.9.0
+```
+
+## GitHub Actions support
+
+You can add an `actions.yml` file similar to this to natively support GitHub
+Actions & dependabot:
+
+```yaml
+name: repo-review
+description: "Runs repo-review"
+inputs:
+  package-dir:
+    description: "Path to Python package, if different from repo root"
+    required: false
+    default: ""
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v4
+      id: python
+      with:
+        python-version: "3.11"
+        update-environment: false
+
+    - name: Run repo-review
+      shell: bash
+      run: >
+        pipx run
+        --python '${{ steps.python.outputs.python-path }}'
+        --spec '${{ github.action_path }}[cli]'
+        repo-review
+        .
+        --package-dir "${{ inputs.package-dir }}"
+        --format split
+        >> $GITHUB_STEP_SUMMARY
+```