Skip to content
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.

Sign up for GitHub

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

Update docs for pre-commit (auto linting) #3332

Merged
merged 4 commits into from
Dec 1, 2017
Merged

Update docs for pre-commit (auto linting) #3332

Changes from 3 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
b623090
Update docs for pre-commit (auto linting)
humitos Nov 29, 2017
d744130
Better explanation on the pre-commit flow
humitos Nov 29, 2017
2a20ae4
Fix grammar and add some more information on pre-commit usage
agjohnson Dec 1, 2017
1243df4
Merge branch 'master' into humitos/docs/linting
agjohnson Dec 1, 2017
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
44 changes: 33 additions & 11 deletions docs/contribute.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,17 +34,37 @@ label. Those tickets are meant to be standalone and can be worked on ad-hoc.
When contributing code, then please follow the standard Contribution
Guidelines set forth at `contribution-guide.org`_.

We have a strict code style that it's easy to follow since you just
have to run a couple of commands and they will do everything for
you. These commands are a mix between `autoflake`_, `autopep8`_,
`docformatter`_, `isort`_, `unify`_ and `yapf`_::

$ autoflake --remove-all-unused-imports --remove-unused-variables --keep-useless-pass
$ autopep8
$ docformatter --wrap-summaries=80 --wrap-descriptions=80 --pre-summary-newline --no-blank
$ isort
$ unify --quote="'"
$ yapf --exclude=*migrations* --exclude=*settings* --exclude=*scripts* --parallel
We have a strict code style that is easy to follow since you just have to
install `pre-commit`_ and it will automatically run different linting tools
(`autoflake`_, `autopep8`_, `docformatter`_, `isort`_, `prospector`_, `unify`_
and `yapf`_) to check your changes before you commit them. `pre-commit` will let
you know if there were any problems that is wasn't able to fix automatically.

To run the `pre-commit` command and check your changes::

$ pip install -U pre-commit
$ git add <your-modified-files>
$ pre-commit run

or to run against a specific file::

$ pre-commit run --files <file.py>

`pre-commit` can also be run as a git pre-commit hook. You can set this up
with::

$ pre-commit install

After this installation, the next time you run `git commit` the `pre-commit run`
command will be run immediately and will inform you of the changes and errors.

.. note::

Our code base is still maturing and the core team doesn't yet recommend
running this as a pre-commit hook due to the number of changes this will
cause while constructing a pull request. Independent pull requests with
linting changes would be a great help to making this possible.


.. _Feature Overview: https://github.com/rtfd/readthedocs.org/issues?direction=desc&labels=Feature+Overview&page=1&sort=updated&state=open
.. _Good First Issue: https://github.com/rtfd/readthedocs.org/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22
Expand All @@ -54,6 +74,8 @@ you. These commands are a mix between `autoflake`_, `autopep8`_,
.. _autoflake: https://github.com/myint/autoflake
.. _autopep8: https://github.com/hhatto/autopep8
.. _docformatter: https://github.com/myint/docformatter
.. _isort: https://github.com/timothycrosley/isort
.. _prospector: https://prospector.landscape.io/en/master
.. _unify: https://github.com/myint/unify
.. _yapf: https://github.com/google/yapf

Expand Down