Skip to content

Commit ae021f2

Browse files
szymonmaszkeszymonmaszke
committed
feat: add project documentation
Signed-off-by: szymonmaszke <[email protected]>
1 parent cddf89d commit ae021f2

File tree

5 files changed

+134
-38
lines changed

5 files changed

+134
-38
lines changed

‎.pre-commit-config.yaml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,7 @@ repos:
6969
name: "<<<CHECK>>> Natural language"
7070
verbose: true
7171
- repo: "https://github.com/rhysd/actionlint"
72-
rev: "03d0035246f3e81f36aed592ffb4bebf33a03106" # frozen: v1.7.7
72+
rev: "e7d448ef7507c20fc4c88a95d0c448b848cd6127" # frozen: v1.7.8
7373
hooks:
7474
- id: "actionlint"
7575
alias: "github-actions-actionlint"

‎.pre-commit-hooks.yaml‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# SPDX-FileCopyrightText: © 2025 open-nudge <https://github.com/open-nudge>
2+
# SPDX-FileContributor: szymonmaszke <[email protected]>
3+
#
4+
# SPDX-License-Identifier: Apache-2.0
5+
6+
---
7+
- id: "pratidoc"
8+
name: "pratidoc"
9+
description: >-
10+
Lint your repository docs - ensure the essentials are always there.
11+
language: "python"
12+
entry: "pratidoc"
13+
args:
14+
- "check"
15+
always_run: true
16+
...

‎CODEOWNERS‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,5 @@
66
# Define the code owners for the repository manually
77
# See: https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners
88
# for more information
9+
10+
* @szymonmaszke

‎README.md‎

Lines changed: 107 additions & 33 deletions
Original file line numberDiff line numberDiff line change
@@ -48,13 +48,25 @@ ______________________________________________________________________
4848

4949
## Features
5050

51-
__pratidoc__ is a … allowing you to:
52-
53-
- __Feature 1__: Description of the feature
54-
- __Feature 2__: Description of the feature
55-
- __Feature 3__: Description of the feature
56-
- __Feature 4__: Description of the feature
57-
- __Feature 5__: Description of the feature
51+
__pratidoc__ is a __documentation checker__ which verifies if your project
52+
contains a set of essential documentation files:
53+
54+
- __Well-defined files__: Only the files common in large open source projects
55+
are searched for.
56+
- __Comprehensive choice__: Documents from a wide range of categories
57+
(like legal, governance, security, community, etc.) are included.
58+
- __Link to source__: Wherever applicable each rule points to the
59+
official/well-respected resource with more information regarding it.
60+
61+
## Table of contents
62+
63+
- [Quick start](#quick-start)
64+
- [Installation](#installation)
65+
- [Usage](#usage)
66+
- [Advanced](#advanced)
67+
- [Configuration](#configuration)
68+
- [Run as a pre-commit hook](#run-as-a-pre-commit-hook)
69+
- [Rules](#rules)
5870

5971
## Quick start
6072

@@ -73,49 +85,111 @@ __pratidoc__ is a … allowing you to:
7385

7486
### Usage
7587

76-
```python
77-
import pratidoc
88+
To check against the rules run the following from the command line:
7889

79-
...
90+
```sh
91+
> pratidoc check
8092
```
8193

82-
### Examples
94+
> [!NOTE]
95+
> The command should be ran from the directory which we want to verify
96+
> __and no path(s) should be passed as arguments!__
8397
84-
<details>
85-
<summary><b><big>Short</big></b> (click me)</summary>
86-
&nbsp;
98+
an example output could be:
8799

88-
Description of the example
89-
90-
```python
91-
# Short example
100+
```sh
101+
> ALL:-:-: PRATIDOC1 Multiple README files exist.
92102
```
93103

94-
</details>
104+
> [!NOTE]
105+
> This is a __repo-wide linter__, therefore it will not point to a specific
106+
> line, instead `ALL:-:-:` means that the rule was violated in
107+
> current working directory.
95108
96-
<details>
97-
<summary><b><big>Common</big></b> (click me)</summary>
98-
&nbsp;
109+
## Advanced
99110

100-
Description of the example
111+
### Configuration
101112

102-
```python
103-
# Common use case
113+
You can configure `pratidoc` in `pyproject.toml` (or `.pratidoc.toml`
114+
in the root of your project, just remove the `[tool.pratidoc]` section),
115+
for example:
116+
117+
```toml
118+
[tool.pratidoc]
119+
# include rules by their code
120+
include_codes = [1, 2, 5] # default: all rules included
121+
# exclude rules by their code (takes precedence over include)
122+
exclude_codes = [4, 5, 6] # default: no rules excluded
123+
# whether to exit after first error or all errors
124+
end_mode = "first" # default: "all"
104125
```
105126

106-
</details>
127+
> [!WARNING]
128+
> You can only disable rules via include/exclude codes as shown above.
107129
108-
<details>
109-
<summary><b><big>Advanced</big></b> (click me)</summary>
110-
&nbsp;
130+
### Run as a pre-commit hook
111131

112-
Description of the example
132+
`pratidoc` can be used as a pre-commit hook, to add as a plugin:
113133

114-
```python
115-
# Something advanced and cool
134+
```yaml
135+
repos:
136+
- repo: "https://github.com/open-nudge/pratidoc"
137+
rev: ... # select the tag or revision you want, or run `pre-commit autoupdate`
138+
hooks:
139+
- id: "pratidoc"
116140
```
117141
118-
</details>
142+
### Rules
143+
144+
> [!TIP]
145+
> Run `pratidoc rules` to see the list of available rules.
146+
147+
`pratidoc` provides the following rules (links omitted for brevity):
148+
149+
| Name | Enabled | Description |
150+
| ---------- | ------- | ------------------------------------------------ |
151+
| PRATIDOC0 | True | File README should be defined. |
152+
| PRATIDOC1 | True | Only one README file should be defined. |
153+
| PRATIDOC2 | True | File SECURITY should be defined. |
154+
| PRATIDOC3 | True | Only one SECURITY file should be defined. |
155+
| PRATIDOC4 | True | File LICENSE should be defined. |
156+
| PRATIDOC5 | True | Only one LICENSE file should be defined. |
157+
| PRATIDOC6 | True | File CHANGELOG should be defined. |
158+
| PRATIDOC7 | True | Only one CHANGELOG file should be defined. |
159+
| PRATIDOC8 | True | File CITATION should be defined. |
160+
| PRATIDOC9 | True | Only one CITATION file should be defined. |
161+
| PRATIDOC10 | True | File DCO should be defined. |
162+
| PRATIDOC11 | True | Only one DCO file should be defined. |
163+
| PRATIDOC12 | True | File ADOPTERS should be defined. |
164+
| PRATIDOC13 | True | Only one ADOPTERS file should be defined. |
165+
| PRATIDOC14 | True | File CODE_OF_CONDUCT should be defined. |
166+
| PRATIDOC15 | True | Only one CODE_OF_CONDUCT file should be defined. |
167+
| PRATIDOC16 | True | File ROADMAP should be defined. |
168+
| PRATIDOC17 | True | Only one ROADMAP file should be defined. |
169+
| PRATIDOC18 | True | File CODEOWNERS should be defined. |
170+
| PRATIDOC19 | True | Only one CODEOWNERS file should be defined. |
171+
| PRATIDOC20 | True | File GOVERNANCE should be defined. |
172+
| PRATIDOC21 | True | Only one GOVERNANCE file should be defined. |
173+
| PRATIDOC22 | True | File CONTRIBUTING should be defined. |
174+
| PRATIDOC23 | True | Only one CONTRIBUTING file should be defined. |
175+
| PRATIDOC24 | True | File SUPPORT should be defined. |
176+
| PRATIDOC25 | True | Only one SUPPORT file should be defined. |
177+
178+
<!-- pyml disable-num-lines 16 line-length-->
179+
180+
You can consult the following resources to learn more about a given document
181+
(click on the name to go to the resource):
182+
183+
- [`README`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
184+
- [`SECURITY`](https://docs.github.com/en/code-security/getting-started/adding-a-security-policy-to-your-repository)
185+
- [`LICENSE`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/licensing-a-repository)
186+
- [`CHANGELOG`](https://keepachangelog.com/en/1.1.0/)
187+
- [`CITATION`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-citation-files)
188+
- [`DCO`](https://wiki.linuxfoundation.org/dco)
189+
- [`CODE_OF_CONDUCT`](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-code-of-conduct-to-your-project)
190+
- [`SUPPORT`](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-support-resources-to-your-project)
191+
- [`CONTRIBUTING`](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/setting-guidelines-for-repository-contributors)
192+
- [`CODEOWNERS`](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)
119193

120194
<!-- md-dead-link-check: off -->
121195

‎SECURITY-SELF-ASSESSMENT.md‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -60,7 +60,8 @@ Lint your repository docs - ensure the essentials are always there.
6060

6161
### Background
6262

63-
TBD
63+
__pratidoc__ is a __documentation checker__ which verifies if your project
64+
contains best practices documents (e.g. `SECURITY.md` or `README.md`)
6465

6566
### Actors
6667

@@ -74,11 +75,11 @@ TBD
7475

7576
### Goals
7677

77-
TBD
78+
Check the essential set of files is present within the repository.
7879

7980
### Non-goals
8081

81-
TBD
82+
Verifying actual content of the files or their coherence.
8283

8384
## Self-assessment use
8485

@@ -148,7 +149,10 @@ file.
148149

149150
### Incident response
150151

151-
TBD
152+
If you discover a security vulnerability within
153+
[`open-nudge/pratidoc`](https://github.com/open-nudge/pratidoc)
154+
please report it as outlined in the
155+
[`SECURITY.md`](SECURITY.md) file or contact [email protected].
152156

153157
## Appendix
154158

0 commit comments

Comments
 (0)