You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Commit 731b3c5
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/guide/contributors/architecture.md
+22-13Lines changed: 22 additions & 13 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,11 @@
1
1
# Project architecture
2
2
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
4
9
5
10
```python exec="1" session="filetree"
6
11
from fnmatch import fnmatch
@@ -15,24 +20,25 @@ descriptions = {
15
20
".venvs": "The virtual environments for all supported Python versions (git-ignored). See [`make setup`][command-setup] command.",
16
21
".vscode": "The configuration for VSCode (git-ignored). See [`make vscode`][command-vscode] command.",
17
22
"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.",
19
24
"docs/reference/api": "Python API reference, injected with [mkdocstrings](https://mkdocstrings.github.io/).",
20
25
"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.",
22
27
"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).",
26
33
"packages/griffelib/src/griffe/_internal": "Our internal API, hidden from users. See [Program structure](#program-structure).",
27
34
"packages/griffecli/tests": "Our test suite. See [Tests](#tests).",
28
35
"packages/griffelib/tests": "Our test suite. See [Tests](#tests).",
29
36
".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.",
31
37
"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 metadataand 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.",
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.
95
101
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`.
97
103
98
104
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.
99
105
@@ -104,7 +110,7 @@ We use [Hatch](https://hatch.pypa.io/latest/) to build source and wheel distribu
104
110
105
111
## Tests
106
112
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.
108
114
109
115
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.
Copy file name to clipboardExpand all lines: docs/guide/contributors/commands.md
+114Lines changed: 114 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,12 @@
1
1
# Management commands
2
2
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
+
3
6
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.
4
7
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
+
5
10
Try typing `make` or `make help` to show the available commands.
Commands are always available: they don't require any Python dependency to be installed.
15
20
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
+
16
33
[](){#command-setup}
17
34
18
35
### `setup`
@@ -109,6 +126,18 @@ Commands are always available: they don't require any Python dependency to be in
109
126
separate_signature: false
110
127
parameter_headings: false
111
128
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
+
112
141
## Tasks
113
142
114
143
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
119
148
-`make allrun duty TASK`, to run a task in *all* environments
120
149
-`make 3.x duty TASK`, to run a task on a specific Python version
121
150
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
+
122
170
[](){#task-build}
123
171
124
172
### `build`
125
173
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
+
126
176
::: duties.build
127
177
options:
128
178
heading_level: 3
@@ -135,6 +185,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
135
185
136
186
### `changelog`
137
187
188
+
When preparing a release, run `make changelog` to generate an entry from commit messages. Review the changes in `CHANGELOG.md` before releasing.
189
+
138
190
::: duties.changelog
139
191
options:
140
192
heading_level: 3
@@ -147,6 +199,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
147
199
148
200
### `check`
149
201
202
+
Before opening a pull request, run `make check` to find quality, typing, documentation, security, and API compatibility issues.
203
+
150
204
::: duties.check
151
205
options:
152
206
heading_level: 3
@@ -159,6 +213,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
159
213
160
214
### `check-api`
161
215
216
+
After changing a public signature, run `make check-api` to compare both packages against their latest Git tag. Review any reported breakages.
217
+
162
218
::: duties.check_api
163
219
options:
164
220
heading_level: 3
@@ -171,6 +227,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
171
227
172
228
### `check-docs`
173
229
230
+
After editing documentation or docstrings, run `make check-docs` to catch build warnings. A successful build writes the site to `site/`.
231
+
174
232
::: duties.check_docs
175
233
options:
176
234
heading_level: 3
@@ -183,6 +241,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
183
241
184
242
### `check-quality`
185
243
244
+
After editing Python code, run `make check-quality` to find lint violations. Fix the reported issues before submitting your changes.
245
+
186
246
::: duties.check_quality
187
247
options:
188
248
heading_level: 3
@@ -191,10 +251,30 @@ Tasks require the Python dependencies to be installed. They use various tools an
191
251
separate_signature: false
192
252
parameter_headings: false
193
253
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
+
194
272
[](){#task-check-types}
195
273
196
274
### `check-types`
197
275
276
+
After changing annotations or return values, run `make check-types` to find type errors across the configured Python versions.
277
+
198
278
::: duties.check_types
199
279
options:
200
280
heading_level: 3
@@ -207,6 +287,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
207
287
208
288
### `coverage`
209
289
290
+
After running tests, run `make coverage` to identify missing test cases. Open `htmlcov/index.html` to see which lines were not executed.
291
+
210
292
::: duties.coverage
211
293
options:
212
294
heading_level: 3
@@ -219,6 +301,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
219
301
220
302
### `docs`
221
303
304
+
While editing documentation, run `make docs` and open <http://localhost:8000>. The local preview updates when you save changes.
305
+
222
306
::: duties.docs
223
307
options:
224
308
heading_level: 3
@@ -231,6 +315,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
231
315
232
316
### `docs-deploy`
233
317
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
+
234
320
::: duties.docs_deploy
235
321
options:
236
322
heading_level: 3
@@ -243,6 +329,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
243
329
244
330
### `format`
245
331
332
+
Before checking Python changes, run `make format` to apply formatting and automatic lint fixes. Review the resulting diff before committing.
333
+
246
334
::: duties.format
247
335
options:
248
336
heading_level: 3
@@ -255,6 +343,14 @@ Tasks require the Python dependencies to be installed. They use various tools an
255
343
256
344
### `fuzz`
257
345
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
+
258
354
::: duties.fuzz
259
355
options:
260
356
heading_level: 3
@@ -267,6 +363,8 @@ Tasks require the Python dependencies to be installed. They use various tools an
267
363
268
364
### `publish`
269
365
366
+
After building release distributions, maintainers can run `make publish` to upload files from `dist/` to PyPI.
367
+
270
368
::: duties.publish
271
369
options:
272
370
heading_level: 3
@@ -279,6 +377,14 @@ Tasks require the Python dependencies to be installed. They use various tools an
279
377
280
378
### `release`
281
379
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
+
282
388
::: duties.release
283
389
options:
284
390
heading_level: 3
@@ -291,6 +397,14 @@ Tasks require the Python dependencies to be installed. They use various tools an
291
397
292
398
### `test`
293
399
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`:
Copy file name to clipboardExpand all lines: docs/guide/contributors/index.md
+3Lines changed: 3 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,8 @@
1
1
# Contributor guide
2
2
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
+
3
6
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:
Copy file name to clipboardExpand all lines: docs/guide/contributors/setup.md
+7-2Lines changed: 7 additions & 2 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,6 +1,9 @@
1
1
# Environment setup
2
2
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.
4
7
5
8
## Requirements
6
9
@@ -104,4 +107,6 @@ The setup command will install all the Python dependencies required to work on t
104
107
105
108
## IDE setup
106
109
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