Skip to content

Commit

Permalink
Create doc site for pydoclint (#47)
Browse files Browse the repository at this point in the history
  • Loading branch information
@jsh9
jsh9 authored Jul 23, 2023
1 parent 2b9caf0 commit 5ad3126
Show file tree
Hide file tree
Showing 11 changed files with 660 additions and 240 deletions.
13 changes: 13 additions & 0 deletions .pre-commit-config.yaml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,3 +24,16 @@ repos:
rev: v3.3.3
hooks:
- id: validate_manifest

- repo: https://github.com/jsh9/markdown-toc-creator
rev: 0.0.4
hooks:
- id: markdown-toc-creator

- repo: local
hooks:
- id: copy_readme
name: copy_readme
entry: python .pre_commit_helper_scripts/copy_readme.py
language: system
types: [python]
7 changes: 7 additions & 0 deletions .pre_commit_helper_scripts/copy_readme.py
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
"""Copy `README.md` into `docs/index.md` at every pre-commit runs"""

with open('README.md', encoding='UTF-8') as fp:
lines = fp.readlines()

with open('docs/index.md', 'w', encoding='UTF-8') as fp:
fp.writelines(lines)
7 changes: 7 additions & 0 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# Change Log

## [0.1.4] - 2023-07-23

- Added
- A documentation site to complement README
- Full diff
- https://github.com/jsh9/pydoclint/compare/0.1.3...0.1.4

## [0.1.3] - 2023-07-21

- Fixed
Expand Down
283 changes: 44 additions & 239 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@
A Python docstring linter to check whether a docstring's sections (arguments,
returns, raises, ...) match the function signature or function implementation.

It runs really fast. In fact, it is at least ~1,475 times faster than
It runs really fast. In fact, it can be thousands of times faster than
[darglint](https://github.com/terrencepreilly/darglint) (or its maintained fork
[darglint2](https://github.com/akaihola/darglint2)).

Expand All @@ -14,6 +14,9 @@ Here is a comparison of linting time on some famous Python projects:
| [numpy](https://github.com/numpy/numpy) | 2.0 sec | 49 min 9 sec (1,475x slower) |
| [scikit-learn](https://github.com/scikit-learn/scikit-learn) | 2.4 sec | 3 hr 5 min 33 sec (4,639x slower) |

Additionally, _pydoclint_ can detect some quite a few style violations that
darglint cannot.

Currently, _pydoclint_ supports three docstring styles:

- The [numpy stlyle](https://numpydoc.readthedocs.io/en/latest/format.html)
Expand All @@ -25,6 +28,25 @@ Currently, _pydoclint_ supports three docstring styles:
Another note: this linter and [pydocstyle](https://github.com/PyCQA/pydocstyle)
serves complementary purposes. It is recommended that you use both together.

---

**Table of Contents**

<!--TOC-->

- [1. Installation](#1-installation)
- [2. Usage](#2-usage)
- [2.1. As a native command line tool](#21-as-a-native-command-line-tool)
- [2.2. As a _flake8_ plugin](#22-as-a-flake8-plugin)
- [2.3. As a pre-commit hook](#23-as-a-pre-commit-hook)
- [2.4. Native vs _flake8_](#24-native-vs-flake8)
- [2.5. How to configure _pydoclint_](#25-how-to-configure-pydoclint)
- [3. Style violation codes](#3-style-violation-codes)
- [4. Notes for users](#4-notes-for-users)
- [5. Notes for developers](#5-notes-for-developers)

<!--TOC-->

## 1. Installation

```
Expand Down Expand Up @@ -58,7 +80,7 @@ other built-in _flake8_ linters on your code.

### 2.3. As a pre-commit hook

`pydoclint` is configured for [pre-commit](https://pre-commit.com/) and can be
_pydoclint_ is configured for [pre-commit](https://pre-commit.com/) and can be
set up as a hook with the following `.pre-commit-config.yaml` configuration:

```yaml
Expand All @@ -84,251 +106,34 @@ Here's comparison:

\*) This feature may be added in the near future

### 2.5. Configuration

Here is how to configure _pydoclint_. For detailed explanations of all options,
see [Section 4](#4-configuration-options) below.

#### 2.5.1. Setting options inline

- Native:

```bash
pydoclint --check-arg-order=False <FILE_OR_FOLDER_PATH>
```

- Flake8:
### 2.5. How to configure _pydoclint_

```bash
flake8 --check-arg-order=False <FILE_OR_FOLDER_PATH>
```

#### 2.5.2. Setting options in a configuration file

- Native:

- In a `.toml` file somewhere in your project folder, add a section like this
(put in the config that you need):

```toml
[tool.pydoclint]
style = 'google'
exclude = '\.git|\.tox|tests/data|some_script\.py'
require-return-section-when-returning-none = true
```

- Then, specify the path of the `.toml` file in your command:

```bash
pydoclint --config=path/to/my/config.toml <FILE_OR_FOLDER_PATH>
```

- Flake8:
- In your flake8 config file (see
[flake8's official doc](https://flake8.pycqa.org/en/latest/user/configuration.html#configuration-locations)),
add the config you need under the section `[flake8]`
Please read this page:
[How to configure _pydoclint_](https://jsh9.github.io/pydoclint/how_to_config.html)

## 3. Style violation codes

_pydoclint_ currently has the following style violation codes:

### 3.0. `DOC0xx`: Docstring parsing issues

| Code | Explanation |
| -------- | ---------------------------------------- |
| `DOC001` | Potential formatting errors in docstring |

### 3.1. `DOC1xx`: Violations about input arguments

| Code | Explanation |
| -------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DOC101` | Docstring contains fewer arguments than in function signature |
| `DOC102` | Docstring contains more arguments than in function signature |
| `DOC103` | Docstring arguments are different from function arguments. (Or could be other formatting issues: https://github.com/jsh9/pydoclint#notes-on-doc103) |
| `DOC104` | Arguments are the same in the docstring and the function signature, but are in a different order. |
| `DOC105` | Argument names match, but type hints do not match |
| `DOC106` | The option `--arg-type-hints-in-signature` is `True` but there are no argument type hints in the signature |
| `DOC107` | The option `--arg-type-hints-in-signature` is `True` but not all args in the signature have type hints |
| `DOC108` | The option `--arg-type-hints-in-signature` is `False` but there are argument type hints in the signature |
| `DOC109` | The option `--arg-type-hints-in-docstring` is `True` but there are no type hints in the docstring arg list |
| `DOC110` | The option `--arg-type-hints-in-docstring` is `True` but not all args in the docstring arg list have type hints |
| `DOC111` | The option `--arg-type-hints-in-docstring` is `False` but there are type hints in the docstring arg list |

#### Notes on `DOC103`:

Other potential causes to `DOC103` include:

- Numpy docstring style requires this style: `arg1 : int` (a space between
`arg1` and `:`) but people sometimes write `arg1: int`. This will trigger
`DOC103`.
- In the Google style, writing an `Args:` section without the preceding summary
will also trigger `DOC103`.

### 3.2. `DOC2xx`: Violations about return argument(s)

| Code | Explanation |
| -------- | ---------------------------------------------------------------------------------------------------- |
| `DOC201` | Function/method does not have a return section in docstring |
| `DOC202` | Function/method has a return section in docstring, but there are no return statements or annotations |
| `DOC203` | Return type(s) in the docstring not consistent with the return annotation |

Note on `DOC201`: Methods with `@property` as its last decorator do not need to
have a return section.

### 3.3. `DOC3xx`: Violations about class docstring and class constructor

| Code | Explanation |
| -------- | ------------------------------------------------------------------------------------------------------- |
| `DOC301` | `__init__()` should not have a docstring; please combine it with the docstring of the class |
| `DOC302` | The class docstring does not need a "Returns" section, because `__init__()` cannot return anything |
| `DOC303` | The `__init__()` docstring does not need a "Returns" section, because it cannot return anything |
| `DOC304` | Class docstring has an argument/parameter section; please put it in the `__init__()` docstring |
| `DOC305` | Class docstring has a "Raises" section; please put it in the `__init__()` docstring |
| `DOC306` | The class docstring does not need a "Yields" section, because `__init__()` cannot yield anything |
| `DOC307` | The `__init__()` docstring does not need a "Yields" section, because `__init__()` cannot yield anything |

### 3.4. `DOC4xx`: Violations about "yield" statements

| Code | Explanation |
| -------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `DOC401` | Function/method returns a Generator, but the docstring does not have a "Yields" section |
| `DOC402` | Function/method has "yield" statements, but the docstring does not have a "Yields" section |
| `DOC403` | Function/method has a "Yields" section in the docstring, but there are no "yield" statements or a Generator return annotation |

### 3.5. `DOC5xx`: Violations about "raise" statements

| Code | Explanation |
| -------- | --------------------------------------------------------------------------------------------------------- |
| `DOC501` | Function/method has "raise" statements, but the docstring does not have a "Raises" section |
| `DOC502` | Function/method has a "Raises" section in the docstring, but there are not "raise" statements in the body |

## 4. Configuration options

There are several configuration options available. They can be used invidually
or together.

### 4.1. `--quiet` (shortform: `-q`)

This flag activates the "quite mode", in which no output will be printed to the
command line if there are no violations.

By default, this flag is _not_ activated, so the files that are scanned are
printed in the command line.

```
pydoclint --quiet <FILE_OR_FOLDER>
```
This option is only available in the "native" command-line mode, rather than in
flake8. If you use pydoclint in flake8, please use flake8's own verbosity
configuration instead.
### 4.2. `--exclude`
You can use this option to exclude files within the given folder. It is a regex
pattern of full file paths.
For example:
```
pydoclint --exclude='\.git|\.tox|tests/data' <FOLDER_NAME>
```
This option is only available in the native command-line mode. If you use
_pydoclint_ within _flake8_, you can use _flake8_'s
[`--exclude` option](https://flake8.pycqa.org/en/latest/user/options.html#cmdoption-flake8-exclude).
### 4.3. `--style`
Which style of docstring is your code base using. Right now there are two
available choices: `numpy` and `google`. The default value is `numpy`.
```
pydoclint --style=google <FILE_OR_FOLDER>
```
or
```
flake8 --style=google <FILE_OR_FOLDER>
```
### 4.4. `--arg-type-hints-in-docstring` and `--arg-type-hints-in-signature`
- `--arg-type-hints-in-docstring`
- Shortform: `-thd`
- Default: `True`
- Meaning:
- If `True`, there need to be type hints in the argument list of a
docstring
- If `False`, there cannot be any type hints in the argument list of a
docstring
- `--arg-type-hints-in-signature`
- Shortform: `-ths`
- Default: `True`
- Meaning:
- If `True`, there need to be argument type hints in the function/method
signature
- If `False`, there cannot be any argument type hints in the
function/method signature
Note: if users choose `True` for both options, the argument type hints in the
signature and in the docstring need to match, otherwise there will be a style
violation.
### 4.5. `--check-arg-order` (shortform: `-ao`, default: `True`)
If `True`, the input argument order in the docstring needs to match that in the
function signature.
To turn this option on/off, do this:
```
pydoclint --check-arg-order=False <FILE_OR_FOLDER>
```
or
```
flake8 --check-arg-order=False <FILE_OR_FOLDER>
```
### 4.6. `--skip-checking-short-docstrings` (shortform: `-scsd`, default: `True`)
If `True`, `pydoclint` won't check functions that have only a short description
in their docstring.
To turn this option on/off, do this:
```
pydoclint --skip-checking-short-docstrings=False <FILE_OR_FOLDER>
```
or
```
flake8 --skip-checking-short-docstrings=False <FILE_OR_FOLDER>
```
### 4.7. `--skip-checking-raises` (shortform: `-scr`, default: `False`)
_pydoclint_ currently has 6 categories of style violation codes:

If `True`, _pydoclint_ won't report `DOC501` or `DOC502` if there are `raise`
statements in the function/method but there aren't any "raises" sections in the
docstring (or vice versa).
- `DOC0xx`: Docstring parsing issues
- `DOC1xx`: Violations about input arguments
- `DOC2xx`: Violations about return argument(s)
- `DOC3xx`: Violations about class docstring and class constructor
- `DOC4xx`: Violations about "yield" statements
- `DOC5xx`: Violations about "raise" statements

### 4.8. `--allow-init-docstring` (shortform: `-aid`, default: `False`)
For detailed explanations of each violation code, please read this page:
[_pydoclint_ style violation codes](https://jsh9.github.io/pydoclint/violation_codes.html).

If it is set to `True`, having a docstring for class constructors
(`__init__()`) is allowed, and the arguments are expected to be documented
under `__init__()` rather than in the class docstring.
## 4. Notes for users

### 4.9. `--require-return-section-when-returning-none` (shortform: `-rrs`, default: `False`)
If you'd like to use _pydoclint_ for your project, it is recommended that you
read these additional notes
[here](https://jsh9.github.io/pydoclint/notes_for_users.html).

If `False`, a "return" section is not necessary in the docstring if the
function implicitly returns `None` (for example, doesn't have a return
statement, or has `-> None` as the return annotation).
## 5. Notes for developers

### 4.10. `--check-return-types` (shortform: `-crt`, default: `True`)
If you'd like to contribute to the code base of _pydoclint_, thank you!

If True, check that the type(s) in the docstring return section and the return
annotation in the function signature are consistent
[This guide](https://jsh9.github.io/pydoclint/notes_for_developers.html) can
hopefully help you get familiar with the code base faster.
Loading

0 comments on commit 5ad3126

Please sign in to comment.