writing docs with rst and sphinx

.vscode/settings.json

@@ -2,5 +2,6 @@
     "python.formatting.provider": "black",
     "python.linting.pylintEnabled": false,
     "python.linting.flake8Enabled": true,
-    "python.linting.enabled": true
+    "python.linting.enabled": true,
+    "restructuredtext.confPath": "${workspaceFolder}/venv/lib/python3.8/site-packages/django/urls"
 }

CONTRIBUTORS

@@ -1,3 +1,4 @@
 - James McMahon
 - Eshaan Bansal
+- Shabda Raaj
 - Matteo Lodi

README.md

@@ -15,17 +15,12 @@ The idea is to provide one library that does token auth for multiple Web/CLI/Mob
 Durin authentication is token based, similar to the `TokenAuthentication`
 built in to DRF. However, it adds some extra sauce:
 
-- Durin allows multiple tokens per user. But only one token each user per API client.
-
+- Durin allows **multiple tokens per user**. But only one token each user per API client.
 - Each user token is associated with an API Client. These API Clients are configurable via Django's Admin Interface.
-
-- All Durin tokens have an expiration time. This expiration time can be different per API client.
-
+- All Durin **tokens have an expiration time**. This expiration time can be different per API client.
 - Durin provides an option for a logged in user to remove *all*
     tokens that the server has - forcing him/her to re-authenticate for all API clients.
-
-- Durin tokens can be renewed to get a fresh expiry.
-
+- Durin **tokens can be renewed** to get a fresh expiry.
 - Durin provides a `CachedTokenAuthentication` backend as well which uses memoization for faster look ups.
 
 More information can be found in the [Documentation](https://django-rest-durin.readthedocs.io/).
@@ -52,4 +47,8 @@ This project is published with the [MIT License](LICENSE). See [https://chooseal
 
 ## Credits
 
-Durin is inpired by the [django-rest-knox](https://github.com/James1345/django-rest-knox) and [django-rest-multitokenauth](https://github.com/anexia-it/django-rest-multitokenauth) libraries and includes some learnings and code from both.
+<<<<<<< HEAD
+Durin is inpired by the [django-rest-knox](https://github.com/James1345/django-rest-knox) and [django-rest-multitokenauth](https://github.com/anexia-it/django-rest-multitokenauth) libraries and includes some learnings and code from both.
+=======
+Durin is inpired by the [django-rest-knox](https://github.com/James1345/django-rest-knox) and [django-rest-multitokenauth](https://github.com/anexia-it/django-rest-multitokenauth) libraries and includes some learnings, docs and code from both.
+>>>>>>> docs

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.http://sphinx-doc.org/
+	exit /b 1
+)
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/requirements.docs.txt

@@ -0,0 +1,11 @@
+../requirements.dev.txt
+commonmark==0.9.1
+docutils==0.16
+Sphinx==3.2.1
+sphinx-rtd-theme
+sphinxcontrib-applehelp==1.0.2
+sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-htmlhelp==1.0.3
+sphinxcontrib-jsmath==1.0.1
+sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-serializinghtml==1.1.4

docs/serve_docs.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+export DJANGO_SETTINGS_MODULE="example_project.settings"
+make html
+cd build/html && python3 -m http.server 6969 && cd ../../

docs/source/auth.rst

@@ -0,0 +1,61 @@
+***************************************
+Authentication (``durin.auth``)
+***************************************
+
+Durin provides one ``TokenAuthentication`` backend and
+``CachedTokenAuthentication`` which uses memoization for faster look ups.
+
+TokenAuthentication
+--------------------------
+
+.. autoclass:: durin.auth.TokenAuthentication
+   :show-inheritance:
+
+Durin tokens should be generated using the provided views.
+Any ``APIView`` or ``ViewSet`` can be accessed using these tokens by adding ``TokenAuthentication``
+to the View's ``authentication_classes``.
+To authenticate, the ``Authorization`` header should be set on the request, like::
+
+    Authorization: Token adee69d0e4bbdc6e4m9836F45E23A325
+
+**Note**: The prefix can be configured by setting the ``REST_DURIN["AUTH_HEADER_PREFIX"]`` (`ref <settings.html#AUTH_HEADER_PREFIX>`__).
+
+**Example Usage**::
+
+    from rest_framework.permissions import IsAuthenticated
+    from rest_framework.response import Response
+    from rest_framework.views import APIView
+
+    from durin.auth import TokenAuthentication
+
+    class ExampleView(APIView):
+        authentication_classes = (TokenAuthentication,)
+        permission_classes = (IsAuthenticated,)
+
+        def get(self, request, *args, **kwargs):
+            content = {
+                'foo': 'bar'
+            }
+            return Response(content)
+
+Tokens expire after a preset time. See `settings.DEFAULT_TOKEN_TTL <settings.html#DEFAULT_TOKEN_TTL>`__.
+
+--------------------------
+
+CachedTokenAuthentication
+--------------------------
+
+.. autoclass:: durin.auth.CachedTokenAuthentication
+   :show-inheritance:
+
+--------------------------
+
+Global usage on all views
+--------------------------
+
+You can activate Durin's :class:`durin.auth.TokenAuthentication` or 
+:class:`durin.auth.CachedTokenAuthentication` on all your views by adding it to 
+``REST_FRAMEWORK["DEFAULT_AUTHENTICATION_CLASSES"]`` under your app's ``settings.py``. 
+Make sure to not use both of these together.
+
+.. Warning:: If you use `Token Authentication` in production you must ensure that your API is only available over HTTPS (SSL).

docs/source/conf.py

@@ -0,0 +1,95 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+import django
+
+# I've simplified this a little to use append instead of insert.
+sys.path.append(os.path.abspath("../../"))
+
+# Specify settings module
+os.environ.setdefault("DJANGO_SETTINGS_MODULE", "example_project.settings")
+
+# Setup Django
+django.setup()
+
+
+# -- Project information -----------------------------------------------------
+
+project = "Django-Rest-Durin"
+copyright = "2020, Eshaan Bansal"
+author = "Eshaan Bansal"
+
+# The full version, including alpha/beta/rc tags
+release = "0.1.0"
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx_rtd_theme",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosectionlabel",
+]
+
+source_suffix = [".rst", ".md"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = []
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+html_theme_path = [
+    "_themes",
+]
+
+# Custom options
+
+# html_context = {
+#     "project_links": [
+#         ProjectLink("Donate To The Author", "https://paypal.me/eshaanbansal"),
+#         ProjectLink(f"{project} Website", f"https://{project}.readthedocs.io/"),
+#         ProjectLink("PyPI releases", f"https://pypi.org/project/{project}/"),
+#         ProjectLink("Source Code", f"https://github.com/eshaan7/{project}"),
+#         ProjectLink("Issue Tracker", f"https://github.com/eshaan7/{project}/issues"),
+#     ]
+# }
+html_sidebars = {
+    "index": ["localtoc.html", "searchbox.html"],
+    "**": ["localtoc.html", "relations.html", "searchbox.html"],
+}
+singlehtml_sidebars = {"index": ["localtoc.html"]}
+html_static_path = ["_static"]
+# html_favicon = "_static/flask-icon.png"
+# html_logo = "_static/flask-icon.png"
+html_title = f"{project} Documentation ({release})"
+
+
+# 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"]

docs/source/contribute.rst

@@ -0,0 +1,28 @@
+Development
+================================
+
+If you would like to contribute to django-rest-durin, you can clone the `respository <https://github.com/Eshaan7/django-rest-durin>`__ from GitHub.
+
+.. parsed-literal::
+    git clone https://github.com/Eshaan7/django-rest-durin
+
+Extra dependencies required during testing or development can be installed with:
+
+.. parsed-literal::
+    pip install django-rest-durin[dev]
+
+Before committing your changes with git or pushing them to remote, please run the following:
+
+    .. parsed-literal::
+bash pre-commit.sh
+
+Run the tests locally
+================================
+
+If you need to debug a test locally and if you have `docker <https://www.docker.com/>`__ installed:
+
+simply run the ``./docker-run-tests.sh`` script and it will run the test suite in every Python /
+Django versions.
+
+You could also simply run regular ``tox`` in the root folder as well, but that would make testing the matrix of
+Python / Django versions a bit more tricky.

docs/source/durin.rst

@@ -0,0 +1,25 @@
+Durin submodules
+==================
+
+``durin.admin`` module
+------------------------------
+
+.. automodule:: durin.admin
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+``durin.models`` module
+------------------------------
+
+.. automodule:: durin.models
+   :members:
+   :show-inheritance:
+
+``durin.serializers`` module
+------------------------------
+
+.. automodule:: durin.serializers
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/source/index.rst

@@ -0,0 +1,55 @@
+Welcome to Django-Rest-Durin!
+================================
+
+.. image:: https://img.shields.io/pypi/v/django-rest-durin
+.. image:: https://img.shields.io/lgtm/grade/python/g/Eshaan7/django-rest-durin.svg?logo=lgtm&logoWidth=18
+.. image:: https://travis-ci.com/Eshaan7/django-rest-durin.svg?branch=main
+.. image:: https://codecov.io/gh/Eshaan7/django-rest-durin/branch/main/graph/badge.svg?token=S9KEI0PU05
+
+Per API client token authentication Module for Django-REST-Framework_
+
+The idea is to provide one library that does token auth for multiple Web/CLI/Mobile API clients via one interface but allows different token configuration for each client.
+
+Durin authentication is token based, similar to the ``TokenAuthentication``
+built in to DRF. However, it adds some extra sauce:
+
+- Durin allows **multiple tokens** per user. But only one token each user per API client.
+- Each user token is associated with an API Client. These API Clients (:class:`durin.models.Client`) are configurable via Django's Admin Interface.
+- All Durin tokens have an expiration time. This expiration time can be different per API client.
+- Durin provides an option for a logged in user to remove **all** tokens that the server has - forcing him/her to re-authenticate for all API clients.
+- Durin **tokens can be renewed** to get a fresh expiry.
+- Durin provides a :class:`durin.auth.CachedTokenAuthentication` backend as well which uses memoization for faster look ups.
+
+.. _Django-REST-Framework: http://www.django-rest-framework.org/
+
+Index
+-------------------------------
+Get started at :doc:`installation`.
+
+.. toctree::
+   :maxdepth: 2
+
+   installation
+   settings
+   auth
+   views
+   urls
+   permissions
+   signals
+   contribute
+
+API Reference
+-------------------------------
+If you are looking for information on a specific function, class or
+method, this part of the documentation is for you.
+
+.. toctree::
+   :maxdepth: 2
+
+   durin
+
+Indices and tables
+================================
+
+* :ref:`genindex`
+* :ref:`modindex`