Added doctest and minor improvements

bobirdmi · Nov 8, 2016 · da0afa1 · hroncok · Nov 15, 2016 · bobirdmi
1 parent 4266aca
commit da0afa1
Show file tree

Hide file tree

Showing 7 changed files with 291 additions and 27 deletions.
diff --git a/README.md b/README.md
@@ -1,26 +1,56 @@
 # githubissuesbot
-GitHub Issues Bot for MI-PYT in FIT CTU in Prague. The program has two modes: console and web app. In *console* mode it labels issues (checks new one with the specified frequency) in the given repository by the issues itself and their comments, and in *web* mode the program labels new opened issue as soon as possible (by [webhook](https://developer.github.com/webhooks/) notification and so one by one). 
+GitHub Issues Bot for MI-PYT in FIT CTU in Prague. The program has two modes: console and web app. In *console* mode it labels [issues](https://help.github.com/articles/creating-an-issue/) (checks new one with the specified frequency) in the given repository by the issues itself and their comments, and in *web* mode the program labels new opened issue as soon as possible (by [webhook](https://developer.github.com/webhooks/) notification and so one by one). 
 
 Link to [testpypi](https://testpypi.python.org/pypi/githubissuesbot).
 
 Link to [Read The Docs](https://readthedocs.org/projects/githubissuesbot/).
 
-### Requirements
+## Requirements
 * python 3.5
 * libraries: [markdown](https://pypi.python.org/pypi/Markdown), [click](http://click.pocoo.org/6/), [requests](http://docs.python-requests.org/en/master/), [flask](http://flask.pocoo.org/), [appdirs](https://pypi.python.org/pypi/appdirs)
 
-### Manual
-Install package by typing the command: **python -m pip install --extra-index-url https://testpypi.python.org/pypi githubissuesbot**
+## Manual
+### Installation
+Install package by typing the command: 
 
-Then you may run the app by typing **python -m githubissuesbot** or just **githubissuesbot**. Type **--help** for command line manual.
+`python -m pip install --extra-index-url https://testpypi.python.org/pypi githubissuesbot`
 
-Read how to generate configuration files by typing **python -m githubissuesbot genconf --help** or **githubissuesbot genconf --help**.
+### Running app
+Then you may run the app by typing 
 
-The app requires the following configuration files: **auth.cfg** (with GitHub personal access token), **label.cfg** (with available labels and the appropriate rules as regular expressions), **secret.cfg** (with [webhook secret token](https://developer.github.com/webhooks/securing/)) and **web.cfg** (web app uses it for reading info about other configuration files).
+`python -m githubissuesbot` or just `githubissuesbot`. 
+
+Type `--help` for command line manual.
+
+### Creating config files
+Read how to generate configuration files by typing 
+
+`python -m githubissuesbot genconf --help` or 
+
+`githubissuesbot genconf --help`.
+
+The app requires the following configuration files: **auth.cfg** (with [GitHub personal access token](https://help.github.com/articles/creating-an-access-token-for-command-line-use/)), **label.cfg** (with available labels and the appropriate rules as regular expressions), **secret.cfg** (with [webhook secret token](https://developer.github.com/webhooks/securing/)) and **web.cfg** (web app uses it for reading info about other configuration files).
 
 If you want to deploy this app on some host (tested on [pythonanywhere](https://www.pythonanywhere.com/)), don't forget to manually fix **web_config_file** value in **web_app.py** on line 39.
 
 ### Running tests
-You may run tests by typing **python setup.py test**.
+You may run tests by typing `python setup.py test`.
 
 You must have file **./tests/fixtures/auth.cfg.truetoken.test**, if you want to rewrite [betamax](https://pypi.python.org/pypi/betamax) cassettes.
+
+### Documentation
+Go to package directory and type
+
+`pip install -r docs/requirements.txt`
+
+Then type the following command in order to generate documentation in HTML 
+
+`cd docs && make html`
+
+And verify code and documentation consistency by typing
+
+`cd docs && make doctest`
+
+You can reindex package modules by typing from the package directory
+
+`python -m sphinx.apidoc -f -o docs githubissuesbot`
diff --git a/README.rst b/README.rst
@@ -1,8 +1,9 @@
 githubissuesbot
-==============
+===============
 
 GitHub Issues Bot for MI-PYT in FIT CTU in Prague. The program has two
-modes: console and web app. In *console* mode it labels issues (checks
+modes: console and web app. In *console* mode it labels
+`issues <https://help.github.com/articles/creating-an-issue/>`__ (checks
 new one with the specified frequency) in the given repository by the
 issues itself and their comments, and in *web* mode the program labels
 new opened issue as soon as possible (by
@@ -26,16 +27,33 @@ Requirements
 Manual
 ~~~~~~
 
+Installation
+~~~~~~~~~~~~
+
 Install package by typing the command:
-**python -m pip install --extra-index-url https://testpypi.python.org/pypi githubissuesbot**
 
-Then you may run the app by typing **python -m githubissuesbot**
-or just **githubissuesbot**. Type **--help** for command line manual.
+``python -m pip install --extra-index-url https://testpypi.python.org/pypi githubissuesbot``
+
+Running app
+~~~~~~~~~~~
+
+Then you may run the app by typing
+
+``python -m githubissuesbot`` or just ``githubissuesbot``.
+
+Type ``--help`` for command line manual.
+
+Creating config files
+~~~~~~~~~~~~~~~~~~~~~
+
+Read how to generate configuration files by typing
+
+``python -m githubissuesbot genconf --help``
 
-Read how to generate configuration files by typing **python -m githubissuesbot genconf --help**
-or **githubissuesbot genconf --help**.
+or ``githubissuesbot genconf --help``.
 
-The app requires the following configuration files: **auth.cfg** (with GitHub personal access token),
+The app requires the following configuration files: **auth.cfg** (with
+`GitHub personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__),
 **label.cfg** (with available labels and the appropriate rules as regular expressions),
 **secret.cfg** (with `webhook secret token <https://developer.github.com/webhooks/securing/>`__)
 and **web.cfg** (web app uses it for reading info about other configuration files).
@@ -44,13 +62,31 @@ If you want to deploy this app on some host (tested on
 `pythonanywhere <https://www.pythonanywhere.com/>`__), don't forget to
 manually fix **web_config_file** value in **web_app.py** on line 39.
 
-Type --help for command line manual.
+Type ``--help`` for command line manual.
 
 Running tests
 ~~~~~~~~~~~~~
 
-You may run tests by typing **python setup.py test**.
+You may run tests by typing ``python setup.py test``.
 
 You must have file **./tests/fixtures/auth.cfg.truetoken.test**, if you want to rewrite
 `betamax <https://pypi.python.org/pypi/betamax>`__ cassettes.
 
+Documentation
+~~~~~~~~~~~~~
+
+Go to package directory and type
+
+``pip install -r docs/requirements.txt``
+
+Then type the following command in order to generate documentation in HTML
+
+``cd docs && make html``
+
+And verify code and documentation consistency by typing
+
+``cd docs && make doctest``
+
+You can reindex package modules by typing from the package directory
+
+``python -m sphinx.apidoc -f -o docs githubissuesbot``
diff --git a/docs/index.rst b/docs/index.rst
@@ -11,6 +11,7 @@ Contents:
 .. toctree::
    :maxdepth: 2
 
+   intro
    modules
 
 

diff --git a/docs/intro.rst b/docs/intro.rst
@@ -0,0 +1,92 @@
+Introduction
+============
+
+GitHub Issues Bot for MI-PYT in FIT CTU in Prague. The program has two
+modes: console and web app. In *console* mode it labels
+`issues <https://help.github.com/articles/creating-an-issue/>`__ (checks
+new one with the specified frequency) in the given repository by the
+issues itself and their comments, and in *web* mode the program labels
+new opened issue as soon as possible (by
+`webhook <https://developer.github.com/webhooks/>`__ notification and so
+one by one).
+
+Link to `testpypi <https://testpypi.python.org/pypi/githubissuesbot>`__.
+
+Link to `Read The Docs <https://readthedocs.org/projects/githubissuesbot/>`__.
+
+Requirements
+~~~~~~~~~~~~
+
+-  python 3.5
+-  libraries: `click <http://click.pocoo.org/6/>`__,
+   `requests <http://docs.python-requests.org/en/master/>`__,
+   `markdown <https://pypi.python.org/pypi/Markdown>`__,
+   `flask <http://flask.pocoo.org/>`__,
+   `appdirs <https://pypi.python.org/pypi/appdirs>`__
+
+Manual
+~~~~~~
+
+Installation
+~~~~~~~~~~~~
+
+Install package by typing the command:
+
+``python -m pip install --extra-index-url https://testpypi.python.org/pypi githubissuesbot``
+
+Running app
+~~~~~~~~~~~
+
+Then you may run the app by typing
+
+``python -m githubissuesbot`` or just ``githubissuesbot``.
+
+Type ``--help`` for command line manual.
+
+Creating config files
+~~~~~~~~~~~~~~~~~~~~~
+
+Read how to generate configuration files by typing
+
+``python -m githubissuesbot genconf --help``
+
+or ``githubissuesbot genconf --help``.
+
+The app requires the following configuration files: **auth.cfg** (with
+`GitHub personal access token <https://help.github.com/articles/creating-an-access-token-for-command-line-use/>`__),
+**label.cfg** (with available labels and the appropriate rules as regular expressions),
+**secret.cfg** (with `webhook secret token <https://developer.github.com/webhooks/securing/>`__)
+and **web.cfg** (web app uses it for reading info about other configuration files).
+
+If you want to deploy this app on some host (tested on
+`pythonanywhere <https://www.pythonanywhere.com/>`__), don't forget to
+manually fix **web_config_file** value in **web_app.py** on line 39.
+
+Type ``--help`` for command line manual.
+
+Running tests
+~~~~~~~~~~~~~
+
+You may run tests by typing ``python setup.py test``.
+
+You must have file **./tests/fixtures/auth.cfg.truetoken.test**, if you want to rewrite
+`betamax <https://pypi.python.org/pypi/betamax>`__ cassettes.
+
+Documentation
+~~~~~~~~~~~~~
+
+Go to package directory and type
+
+``pip install -r docs/requirements.txt``
+
+Then type the following command in order to generate documentation in HTML
+
+``cd docs && make html``
+
+And verify code and documentation consistency by typing
+
+``cd docs && make doctest``
+
+You can reindex package modules by typing from the package directory
+
+``python -m sphinx.apidoc -f -o docs githubissuesbot``
diff --git a/githubissuesbot/github_bot.py b/githubissuesbot/github_bot.py
@@ -16,6 +16,52 @@ class GitHubBot:
     Attributes:
         url (str): Url of issues in the specified repo (ex.: `https://api.github.com/repos/<username>/<repo>/issues`)).
         default_label (str): If no rule may be applied to issue, an issue will be labeled by this string
+
+    If you have token in *auth.cfg.sample file* and labeling rules in *label.cfg* file,
+    you may call this class the following way
+
+    .. testsetup::
+
+       from githubissuesbot import github_bot
+       import os
+
+       auth_cfg_file = os.path.abspath(os.path.join(os.path.dirname(github_bot.__file__))) + '/config/auth.cfg.sample'
+       label_cfg_file = os.path.abspath(os.path.join(os.path.dirname(github_bot.__file__))) + '/config/label.cfg'
+
+    .. testcode::
+
+       from githubissuesbot import github_bot
+
+       bot = github_bot.GitHubBot(auth_cfg_file,
+                    label_cfg_file,
+                    "https://api.github.com/repos/my-username/my-repo/issues",
+                    "default")
+
+    And access its url and default label by invoking
+
+    >>> bot.url
+    'https://api.github.com/repos/my-username/my-repo/issues'
+    >>> bot.default_label
+    'default'
+
+    You can also send GitHub personal access token as parameter and in this case doesn't matter what
+    you have in *auth_cfg_file*
+
+    .. testcode::
+
+       from githubissuesbot import github_bot
+
+       bot = github_bot.GitHubBot(auth_cfg_file,
+                    label_cfg_file,
+                    "https://api.github.com/repos/my-username/my-repo/issues",
+                    "default",
+                    auth_token='mypersonalaccesstoken')
+       print(bot._token)
+
+    .. testoutput::
+
+       mypersonalaccesstoken
+
     """
     def __init__(self, auth_file, label_file, url, default_label, session=None, auth_token=None):
         """
@@ -33,6 +79,7 @@ def __init__(self, auth_file, label_file, url, default_label, session=None, auth
                 If it is None, requests.Session() will be invoked.
             auth_token (str): GitHub Personal Access Token. If it is None, the *auth_file* will be read. Otherwise, the
                 value of this variable will be used for authorization and *auth_file* parameter will be ignored.
+
         """
         self._read_config(auth_file, auth_token, label_file)