Skip to content

Commit c94f1f9

Browse files
authored
Specify objective of project in README (#99)
1 parent fb2f6cc commit c94f1f9

File tree

1 file changed

+27
-4
lines changed

1 file changed

+27
-4
lines changed

README.md

+27-4
Original file line numberDiff line numberDiff line change
@@ -6,10 +6,33 @@
66

77
# Pydocstringformatter
88

9-
A tool to automatically format Python docstrings that tries to follow recommendations
10-
from [`PEP 8`](https://www.python.org/dev/peps/pep-0008/) and
11-
[`PEP 257`](https://www.python.org/dev/peps/pep-0257/). See
12-
[What it does](#what-it-does) for currently supported auto-formatting.
9+
A tool to automatically format Python docstrings to follow recommendations from
10+
[`PEP 8`](https://www.python.org/dev/peps/pep-0008/) and
11+
[`PEP 257`](https://www.python.org/dev/peps/pep-0257/).
12+
13+
See [What it does](#what-it-does) for currently supported auto-formatting.
14+
15+
### Rationale
16+
17+
This project is heavily inspired by
18+
[`docformatter`](https://github.com/PyCQA/docformatter).
19+
20+
When this project was started `docformatter` did not meet all of the requirements the
21+
[`pylint`](https://github.com/PyCQA/pylint) project had for its docstring formatter and
22+
sadly `docformatter` is now also no longer fully supported. Therefore, some contributors
23+
of `pylint` got together and started working on our own formatter to fulfill our needs.
24+
25+
When asked we defined the objective of the tool as:
26+
27+
_"A docstring formatter that follows PEP8 and PEP257 but makes some of the more
28+
'controversial' elements of the PEPs optional"_
29+
30+
See
31+
[the original answer](https://github.com/DanielNoord/pydocstringformatter/issues/38).
32+
33+
As such, the biggest difference between the two is that `pydocstringformatter` fixes
34+
some of the open issues we found in `docformatter`. In general, the output of both
35+
formatters (and any other docstring formatter) should be relatively similar.
1336

1437
## How to install
1538

0 commit comments

Comments
 (0)