Skip to content

Commit 731b3c5

Browse files
committed
docs: Various improvements
Issue-400: #400
1 parent 3faeeb1 commit 731b3c5

10 files changed

Lines changed: 214 additions & 18 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ Thank you for considering contributing to this project!
44

55
We provide a guide for contributors. If you are reading this locally or directly on GitHub, check the following documents:
66

7-
- Contributors guide: [docs/guide/contributors.md](docs/guide/contributors.md)
7+
- Contributor guide: [docs/guide/contributors/index.md](docs/guide/contributors/index.md)
88
- Environment setup: [docs/guide/contributors/setup.md](docs/guide/contributors/setup.md)
99
- Management commands: [docs/guide/contributors/commands.md](docs/guide/contributors/commands.md)
1010
- Development workflow: [docs/guide/contributors/workflow.md](docs/guide/contributors/workflow.md)

‎docs/guide/contributors/architecture.md‎

Lines changed: 22 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,11 @@
11
# Project architecture
22

3-
This document describes how the project is architectured, both regarding boilerplate and actual code. We start by giving an overview of the project's contents:
3+
!!! info "For contributors and maintainers"
4+
This page explains the repository layout and Griffe's implementation. To use the public API, see the [user guide](../users/index.md) and [API reference](../../reference/api/index.md).
5+
6+
This page covers repository tooling, source code, tests, and the relationship between the public and internal APIs.
7+
8+
## Repository layout
49

510
```python exec="1" session="filetree"
611
from fnmatch import fnmatch
@@ -15,24 +20,25 @@ descriptions = {
1520
".venvs": "The virtual environments for all supported Python versions (git-ignored). See [`make setup`][command-setup] command.",
1621
".vscode": "The configuration for VSCode (git-ignored). See [`make vscode`][command-vscode] command.",
1722
"docs": "Documentation sources (Markdown pages). See [`make docs`][task-docs] task.",
18-
"docs/.overrides": "Customization of [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/)' templates.",
23+
"docs/.overrides": "Customization of Zensical templates.",
1924
"docs/reference/api": "Python API reference, injected with [mkdocstrings](https://mkdocstrings.github.io/).",
2025
"config": "Contains our tooling configuration. See [Scripts, configuration](#scripts-configuration).",
21-
"htmlcov": "HTML report for Python code coverage (git-ignored), integrated in the [Coverage report](../coverage/) page. See [`make coverage`][task-coverage] task.",
26+
"htmlcov": "HTML report for Python code coverage (git-ignored). See [`make coverage`][task-coverage] task.",
2227
"scripts": "Our different scripts. See [Scripts, configuration](#scripts-configuration).",
23-
"site": "Documentation site, built with `make run mkdocs build` (git-ignored).",
24-
"src": "The source of our Python package(s). See [Sources](#sources) and [Program structure](#program-structure).",
25-
"src/griffe": "Our public API, exposed to users. See [Program structure](#program-structure).",
28+
"site": "Documentation site, built with `make check-docs` (git-ignored).",
29+
"packages": "The library and CLI workspace packages. See [Sources](#sources) and [Program structure](#program-structure).",
30+
"packages/griffelib": "The library package, including its sources and tests.",
31+
"packages/griffecli": "The command-line interface package, including its sources and tests.",
32+
"packages/griffelib/src/griffe": "Our public library API. See [Program structure](#program-structure).",
2633
"packages/griffelib/src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
2734
"packages/griffecli/tests": "Our test suite. See [Tests](#tests).",
2835
"packages/griffelib/tests": "Our test suite. See [Tests](#tests).",
2936
".copier-answers.yml": "The answers file generated by [Copier](https://copier.readthedocs.io/en/stable/). See [Boilerplate](#boilerplate).",
30-
"devdeps.txt": "Our development dependencies specification. See [`make setup`][command-setup] command.",
3137
"duties.py": "Our project tasks, written with [duty](https://pawamoy.github.io/duty). See [Tasks][tasks].",
32-
".envrc": "The environment configuration, automatically sourced by [direnv](https://direnv.net/). See [commands](../commands/).",
33-
"Makefile": "A dummy makefile, only there for auto-completion. See [commands](../commands/).",
34-
"mkdocs.yml": "The build configuration for our docs. See [`make docs`][task-docs] task.",
35-
"pyproject.toml": "The project metadata and production dependencies.",
38+
".envrc": "The environment configuration, automatically sourced by [direnv](https://direnv.net/). See [Management commands](commands.md).",
39+
"Makefile": "A dummy makefile, only there for auto-completion. See [Management commands](commands.md).",
40+
"zensical.toml": "The build configuration for our docs. See [`make docs`][task-docs] task.",
41+
"pyproject.toml": "Project metadata, dependencies, development dependency groups, and workspace configuration.",
3642
}
3743

3844
def exptree(path):
@@ -93,7 +99,7 @@ copier update --trust --skip-answered
9399

94100
We have a few scripts that let us manage the various maintenance aspects for this project. The entry-point is the `make` script located in the `scripts` folder. It doesn't need any dependency to be installed to run. See [Management commands](commands.md) for more information.
95101

96-
The `make` script can also invoke what we call "[tasks][]". Tasks need our development dependencies to be installed to run. These tasks are written in the `duties.py` file, and the development dependencies are listed in `devdeps.txt`.
102+
The `make` script also invokes [tasks](commands.md#tasks) defined in `duties.py` using the duty task runner. Tasks require development dependencies, listed in the dependency groups in `pyproject.toml`.
97103

98104
The tools used in tasks have their configuration files stored in the `config` folder, to unclutter the root of the repository. The tasks take care of calling the tools with the right options to locate their respective configuration files.
99105

@@ -104,7 +110,7 @@ We use [Hatch](https://hatch.pypa.io/latest/) to build source and wheel distribu
104110

105111
## Tests
106112

107-
Our test suite is located in the `tests` folder. It is located outside of the sources as to not pollute distributions (it would be very wrong to publish a `tests` package as part of our distributions, since this name is extremely common), or worse, the public API. The `tests` folder is however included in our source distributions (`.tar.gz`), alongside most of our metadata and configuration files. Check out our `pyproject.toml` files to get the full list of files included in our source distributions for every individual package within the `packages/` folder.
113+
Tests are located in `packages/griffelib/tests` and `packages/griffecli/tests`, outside the source directories. They are included in source distributions, alongside metadata and configuration files. Each package's `pyproject.toml` lists the included files.
108114

109115
The test suite is based on [pytest](https://docs.pytest.org/en/8.2.x/). Test modules reflect our internal API structure, and except for a few test modules that test specific aspects of our API, each test module tests the logic from the corresponding module in the internal API. For example, `test_finder.py` tests code of the `griffe._internal.finder` internal module, while `test_functions` tests our ability to extract correct information from function signatures, statically. The general rule of thumb when writing new tests is to mirror the internal API. If a test touches to many aspects of the loading process, it can be added to the `test_loader` test module.
110116

@@ -169,6 +175,9 @@ render_public_api(heading_level=4)
169175

170176
### Internal API
171177

178+
!!! info "For contributors and maintainers"
179+
These implementation details explain how Griffe works. Use objects exported by `griffe` when integrating with the library.
180+
172181
```python exec="1" idprefix="internal-" session="comment_blocks" id="internal-api"
173182
import os
174183
if os.getenv("DEPLOY") == "true":

‎docs/guide/contributors/commands.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
# Management commands
22

3+
!!! info "For contributors and maintainers"
4+
Use this page to choose a development task and find its options. Start with [environment setup](setup.md) if dependencies are not installed.
5+
36
The entry-point to run commands to manage the project is our Python `make` script, located in the `scripts` folder. You can either call it directly with `./scripts/make`, or you can use [direnv](https://direnv.net/) to add the script to your command line path. Once direnv is installed and hooked into your shell, allow it once for this directory with `direnv allow`. Now you can directly call the Python script with `make`. The `Makefile` is just here to provide auto-completion.
47

8+
On this page, a **command** is a built-in operation of the `make` script. A **task** is an operation defined in `duties.py`, using the [duty](https://pawamoy.github.io/duty/) task runner. Both are invoked with `make NAME`.
9+
510
Try typing `make` or `make help` to show the available commands.
611

712
```console exec="1" source="console" id="make-help1"
@@ -13,6 +18,18 @@ $ make
1318

1419
Commands are always available: they don't require any Python dependency to be installed.
1520

21+
| Command | Use it to |
22+
| --- | --- |
23+
| [`setup`](#command-setup) | Install development dependencies in the virtual environments. |
24+
| [`help`](#command-help) | List operations or show a task's options. |
25+
| [`run`](#command-run) | Run a tool in the default environment. |
26+
| [`multirun`](#command-multirun) | Run a tool for all configured Python versions. |
27+
| [`allrun`](#command-allrun) | Run a tool in both the default and version-specific environments. |
28+
| [`3.x`](#command-3.x) | Run a tool with a particular Python version. |
29+
| [`clean`](#command-clean) | Remove build artifacts and caches. |
30+
| [`vscode`](#command-vscode) | Configure VSCode for development. |
31+
| [`zed`](#command-zed) | Configure Zed for development. |
32+
1633
[](){#command-setup}
1734

1835
### `setup`
@@ -109,6 +126,18 @@ Commands are always available: they don't require any Python dependency to be in
109126
separate_signature: false
110127
parameter_headings: false
111128

129+
[](){#command-zed}
130+
131+
### `zed`
132+
133+
::: make.zed
134+
options:
135+
heading_level: 3
136+
show_root_heading: false
137+
show_root_toc_entry: false
138+
separate_signature: false
139+
parameter_headings: false
140+
112141
## Tasks
113142

114143
Tasks require the Python dependencies to be installed. They use various tools and libraries to assert code quality, run tests, serve the documentation locally, or build and publish distributions of your project. There are multiple ways to run tasks:
@@ -119,10 +148,31 @@ Tasks require the Python dependencies to be installed. They use various tools an
119148
- `make allrun duty TASK`, to run a task in *all* environments
120149
- `make 3.x duty TASK`, to run a task on a specific Python version
121150

151+
| Task | Use it to |
152+
| --- | --- |
153+
| [`build`](#task-build) | Build distributions locally to check packaging. |
154+
| [`changelog`](#task-changelog) | Prepare a changelog entry before a release (maintainers). |
155+
| [`check`](#task-check) | Run all checks before submitting changes. |
156+
| [`check-api`](#task-check-api) | Look for breaking changes after editing the public API. |
157+
| [`check-docs`](#task-check-docs) | Build documentation and report warnings as errors. |
158+
| [`check-quality`](#task-check-quality) | Check code style and lint rules. |
159+
| [`check-security`](#task-check-security) | Audit dependencies and GitHub Actions workflows. |
160+
| [`check-types`](#task-check-types) | Check types after changing annotations or implementation. |
161+
| [`coverage`](#task-coverage) | Find code that tests do not cover. |
162+
| [`docs`](#task-docs) | Preview documentation while editing. |
163+
| [`docs-deploy`](#task-docs-deploy) | Publish the documentation to GitHub Pages (maintainers). |
164+
| [`format`](#task-format) | Format Python code and apply automatic lint fixes. |
165+
| [`fuzz`](#task-fuzz) | Search for static analysis failures with generated code. |
166+
| [`publish`](#task-publish) | Upload built distributions to PyPI (maintainers). |
167+
| [`release`](#task-release) | Tag and publish a new version (maintainers). |
168+
| [`test`](#task-test) | Check behavior after changing code. |
169+
122170
[](){#task-build}
123171

124172
### `build`
125173

174+
Before a release, run `make build` to check that source and wheel distributions can be built. The resulting files are written to `dist/`.
175+
126176
::: duties.build
127177
options:
128178
heading_level: 3
@@ -135,6 +185,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
135185

136186
### `changelog`
137187

188+
When preparing a release, run `make changelog` to generate an entry from commit messages. Review the changes in `CHANGELOG.md` before releasing.
189+
138190
::: duties.changelog
139191
options:
140192
heading_level: 3
@@ -147,6 +199,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
147199

148200
### `check`
149201

202+
Before opening a pull request, run `make check` to find quality, typing, documentation, security, and API compatibility issues.
203+
150204
::: duties.check
151205
options:
152206
heading_level: 3
@@ -159,6 +213,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
159213

160214
### `check-api`
161215

216+
After changing a public signature, run `make check-api` to compare both packages against their latest Git tag. Review any reported breakages.
217+
162218
::: duties.check_api
163219
options:
164220
heading_level: 3
@@ -171,6 +227,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
171227

172228
### `check-docs`
173229

230+
After editing documentation or docstrings, run `make check-docs` to catch build warnings. A successful build writes the site to `site/`.
231+
174232
::: duties.check_docs
175233
options:
176234
heading_level: 3
@@ -183,6 +241,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
183241

184242
### `check-quality`
185243

244+
After editing Python code, run `make check-quality` to find lint violations. Fix the reported issues before submitting your changes.
245+
186246
::: duties.check_quality
187247
options:
188248
heading_level: 3
@@ -191,10 +251,30 @@ Tasks require the Python dependencies to be installed. They use various tools an
191251
separate_signature: false
192252
parameter_headings: false
193253

254+
[](){#task-check-security}
255+
256+
### `check-security`
257+
258+
After changing dependencies or GitHub Actions workflows, run these audits to find known vulnerabilities and workflow security issues:
259+
260+
```bash
261+
make check-security
262+
```
263+
264+
::: duties.check_security
265+
options:
266+
heading_level: 3
267+
show_root_heading: false
268+
show_root_toc_entry: false
269+
separate_signature: false
270+
parameter_headings: false
271+
194272
[](){#task-check-types}
195273

196274
### `check-types`
197275

276+
After changing annotations or return values, run `make check-types` to find type errors across the configured Python versions.
277+
198278
::: duties.check_types
199279
options:
200280
heading_level: 3
@@ -207,6 +287,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
207287

208288
### `coverage`
209289

290+
After running tests, run `make coverage` to identify missing test cases. Open `htmlcov/index.html` to see which lines were not executed.
291+
210292
::: duties.coverage
211293
options:
212294
heading_level: 3
@@ -219,6 +301,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
219301

220302
### `docs`
221303

304+
While editing documentation, run `make docs` and open <http://localhost:8000>. The local preview updates when you save changes.
305+
222306
::: duties.docs
223307
options:
224308
heading_level: 3
@@ -231,6 +315,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
231315

232316
### `docs-deploy`
233317

318+
When publishing documentation independently of a release, maintainers can run `make docs-deploy`. This builds the site and pushes it to GitHub Pages.
319+
234320
::: duties.docs_deploy
235321
options:
236322
heading_level: 3
@@ -243,6 +329,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
243329

244330
### `format`
245331

332+
Before checking Python changes, run `make format` to apply formatting and automatic lint fixes. Review the resulting diff before committing.
333+
246334
::: duties.format
247335
options:
248336
heading_level: 3
@@ -255,6 +343,14 @@ Tasks require the Python dependencies to be installed. They use various tools an
255343

256344
### `fuzz`
257345

346+
When investigating static analysis failures, generate a small set of Python modules and check whether Griffe can visit them:
347+
348+
```bash
349+
make fuzz size=5
350+
```
351+
352+
To reproduce a failure, pass its seed, for example `make fuzz seeds=12345`. Failing examples are minimized and saved in the system temporary directory.
353+
258354
::: duties.fuzz
259355
options:
260356
heading_level: 3
@@ -267,6 +363,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
267363

268364
### `publish`
269365

366+
After building release distributions, maintainers can run `make publish` to upload files from `dist/` to PyPI.
367+
270368
::: duties.publish
271369
options:
272370
heading_level: 3
@@ -279,6 +377,14 @@ Tasks require the Python dependencies to be installed. They use various tools an
279377

280378
### `release`
281379

380+
After reviewing the changelog, maintainers can publish the corresponding version with:
381+
382+
```bash
383+
make release version=7.8.9
384+
```
385+
386+
Replace `7.8.9` with the version in the changelog. This task commits, tags, pushes, publishes distributions, and deploys documentation. See the [release process](workflow.md#release-process) for the full procedure.
387+
282388
::: duties.release
283389
options:
284390
heading_level: 3
@@ -291,6 +397,14 @@ Tasks require the Python dependencies to be installed. They use various tools an
291397

292398
### `test`
293399

400+
After fixing a bug, run `make test` to check for regressions across the configured Python versions.
401+
402+
To focus on a particular area in the default environment, pass Pytest arguments through `make run`:
403+
404+
```bash
405+
make run duty test -- -k test_finder
406+
```
407+
294408
::: duties.test
295409
options:
296410
heading_level: 3

‎docs/guide/contributors/index.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,8 @@
11
# Contributor guide
22

3+
!!! info "For contributors and maintainers"
4+
This guide explains how to change Griffe itself. To use Griffe in another project, start with the [user guide](../users/index.md).
5+
36
Welcome to the Griffe contributor guide! If you are familiar with Python tooling, development, and contributions to open-source projects, see the [TL;DR](#tldr) at the end, otherwise we recommend you walk through the following pages:
47

58
- [Environment setup](setup.md)

‎docs/guide/contributors/setup.md‎

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Environment setup
22

3-
To work on the project, whether to update the code or the documentation, you will have to setup a development environment.
3+
!!! info "For contributors"
4+
Follow this page to prepare a local checkout for code or documentation changes. To install Griffe for use in another project, see [Installation](../../installation.md).
5+
6+
This page covers the required tools, cloning the repository, installing dependencies, and configuring an editor.
47

58
## Requirements
69

@@ -104,4 +107,6 @@ The setup command will install all the Python dependencies required to work on t
104107

105108
## IDE setup
106109

107-
If you work in VSCode, we provide [a command to configure VSCode](commands.md#vscode) for the project.
110+
If you work in VSCode, use [`make vscode`](commands.md#command-vscode) to configure it for the project.
111+
112+
For Zed, use [`make zed`](commands.md#command-zed).

0 commit comments

Comments
 (0)