Skip to content

Commit

Permalink
Add contributing page to the documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
joowani committed Nov 9, 2017
1 parent ad9b6ed commit 6a32f48
Show file tree
Hide file tree
Showing 11 changed files with 136 additions and 12 deletions.
2 changes: 1 addition & 1 deletion .travis.yml
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,6 @@ install:
- pip install python-coveralls
- python setup.py install
script:
- py.test --cov-report= --cov=kq tests/
- py.test --cov=kq
after_success:
- coveralls
9 changes: 9 additions & 0 deletions README.rst
Original file line number Diff line number Diff line change
Expand Up @@ -129,6 +129,15 @@ You may need to use ``sudo`` depending on your environment setup.
.. _GitHub: https://github.com/joowani/kq


Contributing
============

Please have a look at this page_ before submitting a pull request. Thanks!

.. _page:
http://kq.readthedocs.io/en/master/contributing.html


Credits
=======

Expand Down
6 changes: 3 additions & 3 deletions docs/conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -150,15 +150,15 @@
# html_logo = None

# The name of an image file (relative to this directory) to use as a favicon of
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
#
# html_favicon = None

# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['static']
html_static_path = []

# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
Expand Down Expand Up @@ -342,4 +342,4 @@
#
# texinfo_no_detailmenu = False

autodoc_member_order = 'bysource'
autodoc_member_order = 'bysource'
114 changes: 114 additions & 0 deletions docs/contributing.rst
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
.. _contributing-page:

Contributing
------------

Instructions
============

Before submitting a pull request on GitHub_, please make sure you meet the
**requirements**:

* The pull request points to the dev_ (development) branch.
* All changes are squashed into a single commit (I like to use git rebase -i
to do this).
* The commit message is in present tense (good: "Add feature", bad:
"Added feature").
* Correct and consistent style: Sphinx_-compatible docstrings, using snake
vs. camel casing properly_ and PEP8_ compliance. Use flake8_ (see below).
* No classes/methods/functions with missing docstrings or commented-out lines.
You can refer to existing docstrings for examples.
* The test coverage_ remains at %100. Sometimes you may find yourself having to
write superfluous unit tests to keep this number up. If a piece of code is
trivial and has no need for unittests, use this_ to exclude it from coverage.
* No build failures on TravisCI_. The builds automatically trigger on PR
submissions.
* Does not break backward-compatibility (unless there is a really good reason).
* Compatibility with all supported Python versions (2.7, 3.4, 3.5, 3.6).

.. warning::
The dev branch is occasionally rebased_, and its commit history may be
overwritten in the process (I try very hard never to do this). So before
you begin feature work, git fetch/pull to ensure that branches have not
diverged. If you see git conflicts and just want to start from scratch,
run this command:

.. code-block:: bash
~$ git checkout dev
~$ git fetch origin
~$ git reset --hard origin/dev # THIS WILL WIPE ALL CHANGES
Style
=====

To ensure PEP8_ compliance, run flake8_:

.. code-block:: bash
~$ pip install flake8
~$ git clone https://github.com/joowani/kq.git
~$ cd kq
~$ flake8
You should try to resolve all issues reported. If there is a good reason to
ignore errors from a specific piece of code, however, visit here_ to see how
to exclude the lines from the check.

Testing
=======

To test your changes, run the unit tests that come with **kq** on your
local machine. The tests use pytest_.

To run the unit tests:

.. code-block:: bash
~$ pip install pytest
~$ git clone https://github.com/joowani/kq.git
~$ cd kq
~$ py.test --verbose
To run the unit tests with coverage report:

.. code-block:: bash
~$ pip install coverage pytest pytest-cov
~$ git clone https://github.com/joowani/kq.git
~$ cd kq
~$ py.test --verbose --cov-report=html --cov=kq
~$ # Open the generated file htmlcov/index.html in a browser
Documentation
=============

The documentation (including the README) is written in reStructuredText_ and
uses Sphinx_. To build the HTML version of the documentation on your local
machine:

.. code-block:: bash
~$ pip install sphinx sphinx_rtd_theme
~$ git clone https://github.com/joowani/kq.git
~$ cd kq/docs
~$ sphinx-build . build
~$ # Open the generated file build/index.html in a browser
As always, thanks for your contribution!

.. _rebased: https://git-scm.com/book/en/v2/Git-Branching-Rebasing
.. _dev: https://github.com/joowani/kq/tree/dev
.. _GitHub: https://github.com/joowani/kq
.. _properly: https://stackoverflow.com/questions/159720
.. _PEP8: https://www.python.org/dev/peps/pep-0008/
.. _coverage: https://coveralls.io/github/joowani/kq
.. _this: http://coverage.readthedocs.io/en/latest/excluding.html
.. _TravisCI: https://travis-ci.org/joowani/kq
.. _Sphinx: https://github.com/sphinx-doc/sphinx
.. _flake8: http://flake8.pycqa.org
.. _here: http://flake8.pycqa.org/en/latest/user/violations.html#in-line-ignoring-errors
.. _pytest: https://github.com/pytest-dev/pytest
.. _reStructuredText: https://en.wikipedia.org/wiki/ReStructuredText
3 changes: 2 additions & 1 deletion docs/index.rst
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Requirements
============

- Apache Kafka 0.9+
- Python 2.7+ 3.4+ or 3.5+
- Python 2.7, 3.4, 3.5 or 3.6


Installation
Expand Down Expand Up @@ -53,6 +53,7 @@ Contents
callback
cli
logging
contributing


Credits
Expand Down
2 changes: 1 addition & 1 deletion docs/overview.rst
Original file line number Diff line number Diff line change
Expand Up @@ -55,4 +55,4 @@ Sit back and watch the worker process it in the background:
[INFO] Job 1b92xle0 returned: (1, 2, 3)
And that's essentially all there is to KQ! Continue for more information.
And that's essentially all there is to KQ!
2 changes: 1 addition & 1 deletion kq/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@
--certfile=<certfile> Full path to SSL client certificate
--keyfile=<keyfile> Full path to SSL private key
--crlfile=<crlfile> Full path to SSL crlfile for verifying expiry
--proc-ttl=<proc-ttl> Records read before re-spawning process [default: 5000]
--proc-ttl=<proc-ttl> Records read before respawning process [default: 5000]
--offset=<offset> Kafka consumer offset reset policy [default: latest]
--verbose Turn on debug logging output
--help Display this help menu
Expand Down
2 changes: 1 addition & 1 deletion kq/version.py
Original file line number Diff line number Diff line change
@@ -1 +1 @@
VERSION = '1.3.1'
VERSION = '1.3.2'
3 changes: 2 additions & 1 deletion kq/worker.py
Original file line number Diff line number Diff line change
Expand Up @@ -184,9 +184,10 @@ def _consume_record(self, record):
"""
rec = rec_repr(record)
self._logger.info('Processing {} ...'.format(rec))
# noinspection PyBroadException
try:
job = dill.loads(record.value)
except:
except Exception:
self._logger.warning('{} unloadable. Skipping ...'.format(rec))
else:
# Simple check for job validity
Expand Down
3 changes: 1 addition & 2 deletions tests/test_queue.py
Original file line number Diff line number Diff line change
Expand Up @@ -161,7 +161,7 @@ def test_enqueue_job(producer, logger):
assert new_job.args == [1, 2]
assert new_job.kwargs == {'a': 3}
assert new_job.timeout == 300
assert new_job.key == None
assert new_job.key is None

producer_inst.send.assert_called_with(
'foo', dill.dumps(new_job), key=None
Expand Down Expand Up @@ -223,4 +223,3 @@ def test_flush(producer):
queue = Queue(hosts='host:7000', topic='foo')
queue.flush()
producer_inst.flush.assert_called_once()

2 changes: 1 addition & 1 deletion tests/test_worker.py
Original file line number Diff line number Diff line change
Expand Up @@ -279,4 +279,4 @@ def test_start_proc_ttl_reached(logger, callback):
])
callback.assert_called_with(
'success', success_job, (1, 2, 3), None, None
)
)

0 comments on commit 6a32f48

Please sign in to comment.