Skip to content

Specify objective of project in README #99

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 6 commits into from
May 4, 2022
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
31 changes: 27 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,10 +6,33 @@

# Pydocstringformatter

A tool to automatically format Python docstrings that tries to follow recommendations
from [`PEP 8`](https://www.python.org/dev/peps/pep-0008/) and
[`PEP 257`](https://www.python.org/dev/peps/pep-0257/). See
[What it does](#what-it-does) for currently supported auto-formatting.
A tool to automatically format Python docstrings to follow recommendations from
[`PEP 8`](https://www.python.org/dev/peps/pep-0008/) and
[`PEP 257`](https://www.python.org/dev/peps/pep-0257/).

See [What it does](#what-it-does) for currently supported auto-formatting.

### Rationale

This project is heavily inspired by
[`docformatter`](https://github.com/PyCQA/docformatter).

When this project was started `docformatter` did not meet all of the requirements the
[`pylint`](https://github.com/PyCQA/pylint) project had for its docstring formatter and
sadly `docformatter` is now also no longer fully supported. Therefore, some contributors
of `pylint` got together and started working on our own formatter to fulfill our needs.

When asked we defined the objective of the tool as:

_"A docstring formatter that follows PEP8 and PEP257 but makes some of the more
'controversial' elements of the PEPs optional"_

See
[the original answer](https://github.com/DanielNoord/pydocstringformatter/issues/38).

As such, the biggest difference between the two is that `pydocstringformatter` fixes
some of the open issues we found in `docformatter`. In general, the output of both
formatters (and any other docstring formatter) should be relatively similar.

## How to install

Expand Down