Lint your repository docs - ensure the essentials are always there.
✨ Features 🚀 Quick start 📚 Documentation 🤝 Contribute 👍 Adopters 📜 Legal
pratidoc is a documentation checker which verifies if your project contains a set of essential documentation files:
- Well-defined files: Only the files common in large open source projects are searched for.
- Comprehensive choice: Documents from a wide range of categories (like legal, governance, security, community, etc.) are included.
- Link to source: Wherever applicable each rule points to the official/well-respected resource with more information regarding it.
> pip install pratidocTo check against the rules run the following from the command line:
> pratidoc checkNote
The command should be ran from the directory which we want to verify and no path(s) should be passed as arguments!
an example output could be:
> ALL:-:-: PRATIDOC1 Multiple README files exist.Note
This is a repo-wide linter, therefore it will not point to a specific
line, instead ALL:-:-: means that the rule was violated in
current working directory.
You can configure pratidoc in pyproject.toml (or .pratidoc.toml
in the root of your project, just remove the [tool.pratidoc] section),
for example:
[tool.pratidoc]
# include rules by their code
include_codes = [1, 2, 5] # default: all rules included
# exclude rules by their code (takes precedence over include)
exclude_codes = [4, 5, 6] # default: no rules excluded
# whether to exit after first error or all errors
end_mode = "first" # default: "all"Warning
You can only disable rules via include/exclude codes as shown above.
pratidoc can be used as a pre-commit hook, to add as a plugin:
repos:
- repo: "https://github.com/open-nudge/pratidoc"
rev: ... # select the tag or revision you want, or run `pre-commit autoupdate`
hooks:
- id: "pratidoc"Tip
Run pratidoc rules to see the list of available rules.
pratidoc provides the following rules (links omitted for brevity):
| Name | Enabled | Description |
|---|---|---|
| PRATIDOC0 | True | File README should be defined. |
| PRATIDOC1 | True | Only one README file should be defined. |
| PRATIDOC2 | True | File SECURITY should be defined. |
| PRATIDOC3 | True | Only one SECURITY file should be defined. |
| PRATIDOC4 | True | File LICENSE should be defined. |
| PRATIDOC5 | True | Only one LICENSE file should be defined. |
| PRATIDOC6 | True | File CHANGELOG should be defined. |
| PRATIDOC7 | True | Only one CHANGELOG file should be defined. |
| PRATIDOC8 | True | File CITATION should be defined. |
| PRATIDOC9 | True | Only one CITATION file should be defined. |
| PRATIDOC10 | True | File DCO should be defined. |
| PRATIDOC11 | True | Only one DCO file should be defined. |
| PRATIDOC12 | True | File ADOPTERS should be defined. |
| PRATIDOC13 | True | Only one ADOPTERS file should be defined. |
| PRATIDOC14 | True | File CODE_OF_CONDUCT should be defined. |
| PRATIDOC15 | True | Only one CODE_OF_CONDUCT file should be defined. |
| PRATIDOC16 | True | File ROADMAP should be defined. |
| PRATIDOC17 | True | Only one ROADMAP file should be defined. |
| PRATIDOC18 | True | File CODEOWNERS should be defined. |
| PRATIDOC19 | True | Only one CODEOWNERS file should be defined. |
| PRATIDOC20 | True | File GOVERNANCE should be defined. |
| PRATIDOC21 | True | Only one GOVERNANCE file should be defined. |
| PRATIDOC22 | True | File CONTRIBUTING should be defined. |
| PRATIDOC23 | True | Only one CONTRIBUTING file should be defined. |
| PRATIDOC24 | True | File SUPPORT should be defined. |
| PRATIDOC25 | True | Only one SUPPORT file should be defined. |
You can consult the following resources to learn more about a given document (click on the name to go to the resource):
We welcome your contributions! Start here:
- This project is licensed under the Apache 2.0 License - see the LICENSE file for details.
- This project is copyrighted by open-nudge - the appropriate copyright notice is included in each file.