docs: add recipes and contribution guide

Author: lepture

Makefile

@@ -1,11 +1,5 @@
-.PHONY: clean-pyc clean-build docs test coverage
+.PHONY: clean-pyc clean-build docs
 
-test:
-	@nosetests -s
-
-coverage:
-	@rm -f .coverage
-	@nosetests --with-coverage --cover-package=otpauth --cover-html
 
 clean: clean-build clean-pyc clean-docs
 
@@ -27,6 +21,3 @@ clean-docs:
 
 docs:
 	@$(MAKE) -C docs html
-
-publish-docs: docs
-	@python setup.py upload_sphinx --upload-dir=docs/_build/html/

README.md

@@ -9,3 +9,27 @@ One time password implementations in Python. HOTP and TOTP.
 [![codecov](https://badgen.net/codecov/c/github/authlib/otpauth)](https://codecov.io/gh/authlib/otpauth)
 
 </div>
+
+Usage
+-----
+
+```python
+import otpauth
+
+totp = otpauth.HOTP(b"user-secret")
+
+# generate a code for now
+code: int = totp.generate()
+
+# you may want to convert it to string
+str_code: str = totp.string_code(code)
+
+# verify the code
+totp.verify(code)  # => True
+totp.verify(str_code)  # => True
+```
+
+Copyright
+---------
+
+2013, Hsiaoming Yang. Under BSD-3 license.

README.rst

@@ -3,5 +3,25 @@ OTP Auth
 
 One time password implementations in Python. HOTP and TOTP.
 
-Documentation: https://otp.authlib.org/
-GitHub: https://github.com/authlib/otpauth
+**Documentation**: https://otp.authlib.org/
+**GitHub**: https://github.com/authlib/otpauth
+
+Usage
+-----
+
+Most of the time, you would use a time based one time password. You can generate and
+verify the token with :class:`TOTP`::
+
+    import otpauth
+
+    totp = otpauth.HOTP(b"user-secret")
+
+    # generate a code for now
+    code: int = totp.generate()
+
+    # you may want to convert it to string
+    str_code: str = totp.string_code(code)
+
+    # verify the code
+    totp.verify(code)  # => True
+    totp.verify(str_code)  # => True

docs/_static/example-qr.png

@@ -8,6 +8,8 @@ Here are the list of API reference; it might be helpful for developers.
 HOTP
 ----
 
+Implementation of RFC4226, An HMAC-Based One-Time Password Algorithm.
+
 .. autoclass:: HOTP
    :members:
    :inherited-members:
@@ -17,6 +19,8 @@ HOTP
 TOTP
 ----
 
+Implementation of RFC6238, Time-Based One-Time Password Algorithm.
+
 .. autoclass:: TOTP
    :members:
    :inherited-members:

docs/api.rst

@@ -48,7 +48,8 @@
     'twitter_site': 'authlib',
     'twitter_creator': 'lepture',
     'twitter_url': 'https://twitter.com/authlib',
-    'github_url': 'https://github.com/lepture/otpauth',
+    'github_url': 'https://github.com/authlib/otpauth',
+    'discord_url': 'https://discord.gg/HvBVAeNAaV',
     'nav_links': [
         {'title': 'Sponsor me', 'url': 'https://github.com/sponsors/lepture'}
     ]
@@ -63,3 +64,9 @@
 html_show_sourcelink = False
 
 # html_favicon = "_static/light-icon.svg"
+
+html_context = {
+    "source_type": "github",
+    "source_user": "authlib",
+    "source_repo": "otpauth",
+}

docs/conf.py

@@ -1,2 +1,90 @@
 Contributing
 ============
+
+Thank you for considering contributing to this little library!
+
+
+Support questions
+-----------------
+
+Please don't use the issue tracker for this. The issue tracker is a tool
+to address bugs and feature requests. Use one of the following resources
+for questions about Authlib and its related libraries.
+
+-   The ``#questions`` channel on our Discord chat:
+    https://discord.gg/HvBVAeNAaV
+-   Ask on our `GitHub Discussions`_ for long term discussion or larger
+    questions.
+
+.. _GitHub Discussions: https://github.com/authlib/otpauth/discussions
+
+
+Reporting issues
+----------------
+
+Include the following information in your post:
+
+-   Describe what you expected to happen.
+-   If possible, include a `minimal reproducible example`_ to help us
+    identify the issue. This also helps check that the issue is not with
+    your own code.
+-   Describe what actually happened. Include the full traceback if there
+    was an exception.
+-   List your Python and ``otpauth`` versions. If possible, check if this
+    issue is already fixed in the latest releases or the latest code in
+    the repository.
+
+.. _minimal reproducible example: https://stackoverflow.com/help/minimal-reproducible-example
+
+
+Submitting patches
+------------------
+
+If you found something you can improve, a "Pull Request" is always
+welcoming. Here are something you need to notice before submitting
+the PR.
+
+If there is not an open issue for what you want to submit, prefer
+opening one for discussion before working on a PR. You can work on any
+issue that doesn't have an open PR linked to it or a maintainer assigned
+to it. These show up in the sidebar. No need to ask if you can work on
+an issue that interests you.
+
+Include the following in your patch:
+
+-   Use `Black`_ to format your code. This and other tools will run
+    automatically if you install `pre-commit`_ using the instructions
+    below.
+-   Include tests if your patch adds or changes code. Make sure the test
+    fails without your patch.
+-   Update any relevant docs pages and docstrings. Docs pages and
+    docstrings should be wrapped at 72 characters.
+-   Add an entry in ``CHANGES.rst``. Use the same style as other
+    entries. Also include ``.. versionchanged::`` inline changelogs in
+    relevant docstrings.
+
+.. _Black: https://black.readthedocs.io
+.. _pre-commit: https://pre-commit.com
+
+Running the tests
+~~~~~~~~~~~~~~~~~
+
+Run the basic test suite with pytest.
+
+.. code-block:: text
+
+    $ pytest
+
+
+Updating the docs
+~~~~~~~~~~~~~~~~~
+
+When something has been changed, document them in the docs. You may need
+to add a change log in the ``changelog.rst`` file.
+
+Conventional Commits
+~~~~~~~~~~~~~~~~~~~~
+
+We are using `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_.
+When you ``git commit`` some changes, please follow the "Conventional Commits" for the
+commit message.

docs/contribute.rst

@@ -1,6 +1,19 @@
 OTP Auth
 ========
 
+One time password implementations in Python. HOTP and TOTP.
+
+.. note::
+
+    This is a redesigned "v2" of otpauth. Get "v1" documentation
+    at https://pythonhosted.org/otpauth/.
+
+"v1" is considered stable, you may still use it. But "v2" has some
+enhancements:
+
+- **Type hints**: your editor will love it.
+- **No Python 2**: clean code without compatible patches.
+
 Installation
 ------------
 

docs/index.rst

@@ -3,18 +3,112 @@
 User Guide
 ==========
 
+Here are the detail guide on how to use TOTP and HOTP.
+
 .. _totp:
 
 Use TOTP
 --------
 
-Use ``base32`` Secret
-~~~~~~~~~~~~~~~~~~~~~
+TOTP is a **Time-Based One-Time Password Algorithm** defined in
+RFC6238_.
 
-Add to Authenticator App
-~~~~~~~~~~~~~~~~~~~~~~~~
+.. _RFC6238: https://www.rfc-editor.org/rfc/rfc6238
+
+.. code-block:: python
+
+    import time
+    from otpauth import TOTP
+
+    totp = TOTP(b"user-secret")
+
+    # generate a code for now
+    code: int = totp.generate()
+
+    totp.verify(code)  # True
+
+    time.sleep(31)
+    totp.verify(code)  # False
+
+Most of the time, you DO NOT NEED TO change the default configuration,
+but if you want, here is how:
+
+.. code-block:: python
+
+    totp = TOTP(b"user-secret", digit=8, algorithm="SHA256")
 
 .. _hotp:
 
 Use HOTP
 --------
+
+HOTP is a **An HMAC-Based One-Time Password Algorithm** defined in
+RFC4226_.
+
+.. _RFC4226: https://www.rfc-editor.org/rfc/rfc4226
+
+
+.. code-block:: python
+
+    from otpauth import HOTP
+
+    htop = HOTP(b"user-secret")
+
+    # generate a code for now
+    code: int = htop.generate(4)
+
+    htop.verify(code, 4)  # True
+    htop.verify(code, 6)  # False
+
+.. tip:: TOTP is based on HOTP, most of the time you would use HOTP.
+
+Use ``base32`` Secret
+---------------------
+
+When the **secret** you have is a ``base32`` encoded string, you don't have to
+decode it yourself. Instead, you can create the :class:`TOTP` and :class:`HTOP`
+instance with:
+
+.. code-block:: python
+
+    totp = TOTP.from_b32encode("OB4XI2DPNY")
+    hotp = HOTP.from_b32encode("OB4XI2DPNY")
+
+It works well with and without the padding ``=``. e.g.:
+
+.. code-block:: python
+
+    totp = TOTP.from_b32encode("OB4XI2DPNY======")
+    hotp = HOTP.from_b32encode("OB4XI2DPNY======")
+
+This method also accepts secret in bytes.
+
+Add to Authenticator App
+------------------------
+
+There is a method ``.to_uri`` to generate the URI that most authenticator apps
+support. The `Key URI Format`_ looks like:
+
+
+.. code-block:: text
+
+    otpauth://TYPE/LABEL?PARAMETERS
+
+.. _`Key URI Format`: https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+
+An example of :meth:`TOTP.to_uri`:
+
+.. code-block:: python
+
+    >>> totp = TOTP.from_b32encode("OB4XI2DPNY")
+    >>> totp.to_uri("Typlog:lepture.com", "Authlib")
+    "otpauth://totp/Typlog:lepture.com?secret=OB4XI2DPNY&issuer=Authlib&algorithm=SHA1&digits=6&period=30"
+
+Here shows the QR code of this URI:
+
+.. figure:: _static/example-qr.png
+   :align: center
+   :width: 160
+   :height: 160
+
+   You can test with an authenticator app.