Merge pull request #73 from datopian/feature/69-more-documentation

Feature/69 more documentation

dev-requirements.in

@@ -1,4 +1,4 @@
-pip-tools==5.1.*
+pip-tools==5.5.*
 pytest==5.3.*
 pytest-flake8==1.0.*
 pytest-isort==1.*
@@ -11,3 +11,4 @@ pytest-vcr==1.*
 sphinx==3.*
 sphinx-autodoc-typehints[type_comments]==1.*
 recommonmark==0.*
+furo==2021.2.28b28

dev-requirements.txt

@@ -4,63 +4,142 @@
 #
 #    pip-compile --no-index --output-file=dev-requirements.txt dev-requirements.in
 #
-alabaster==0.7.12         # via sphinx
-attrs==20.3.0             # via pytest
-babel==2.9.0              # via sphinx
-certifi==2020.12.5        # via requests
-chardet==4.0.0            # via requests
-click==7.1.2              # via pip-tools
-commonmark==0.9.1         # via recommonmark
-coverage==5.3.1           # via pytest-cov
-docutils==0.16            # via recommonmark, sphinx
-filelock==3.0.12          # via pytest-mypy
-flake8==3.8.4             # via pytest-flake8
-idna==2.10                # via requests, yarl
-imagesize==1.2.0          # via sphinx
-isort==5.7.0              # via pytest-isort
-jinja2==2.11.2            # via sphinx
-markupsafe==1.1.1         # via jinja2
-mccabe==0.6.1             # via flake8
-more-itertools==8.6.0     # via pytest
-multidict==5.1.0          # via yarl
-mypy-extensions==0.4.3    # via mypy
-mypy==0.790               # via pytest-mypy
-packaging==20.8           # via pytest, sphinx
-pip-tools==5.1.2          # via -r dev-requirements.in
-pluggy==0.13.1            # via pytest
-py==1.10.0                # via pytest
-pycodestyle==2.6.0        # via flake8
-pyflakes==2.2.0           # via flake8
-pygments==2.7.3           # via sphinx
-pyparsing==2.4.7          # via packaging
-pytest-cov==2.8.1         # via -r dev-requirements.in
-pytest-env==0.6.2         # via -r dev-requirements.in
-pytest-flake8==1.0.7      # via -r dev-requirements.in
-pytest-isort==1.2.0       # via -r dev-requirements.in
-pytest-mypy==0.5.0        # via -r dev-requirements.in
-pytest-vcr==1.0.2         # via -r dev-requirements.in
-pytest==5.3.5             # via -r dev-requirements.in, pytest-cov, pytest-env, pytest-flake8, pytest-mypy, pytest-vcr
-pytz==2020.5              # via babel
-pyyaml==5.3.1             # via vcrpy
-recommonmark==0.7.1       # via -r dev-requirements.in
-requests==2.25.1          # via sphinx
-six==1.15.0               # via pip-tools, vcrpy
-snowballstemmer==2.0.0    # via sphinx
-sphinx-autodoc-typehints[type_comments]==1.11.1  # via -r dev-requirements.in
-sphinx==3.4.2             # via -r dev-requirements.in, recommonmark, sphinx-autodoc-typehints
-sphinxcontrib-applehelp==1.0.2  # via sphinx
-sphinxcontrib-devhelp==1.0.2  # via sphinx
-sphinxcontrib-htmlhelp==1.0.3  # via sphinx
-sphinxcontrib-jsmath==1.0.1  # via sphinx
-sphinxcontrib-qthelp==1.0.3  # via sphinx
-sphinxcontrib-serializinghtml==1.1.4  # via sphinx
-typed-ast==1.4.2          # via mypy
-typing-extensions==3.7.4.3  # via mypy
-urllib3==1.26.2           # via requests
-vcrpy==4.1.1              # via pytest-vcr
-wcwidth==0.2.5            # via pytest
-wrapt==1.12.1             # via vcrpy
-yarl==1.6.3               # via vcrpy
+alabaster==0.7.12
+    # via sphinx
+attrs==20.3.0
+    # via pytest
+babel==2.9.0
+    # via sphinx
+beautifulsoup4==4.9.3
+    # via furo
+certifi==2020.12.5
+    # via requests
+chardet==4.0.0
+    # via requests
+click==7.1.2
+    # via pip-tools
+commonmark==0.9.1
+    # via recommonmark
+coverage==5.3.1
+    # via pytest-cov
+docutils==0.16
+    # via
+    #   recommonmark
+    #   sphinx
+filelock==3.0.12
+    # via pytest-mypy
+flake8==3.8.4
+    # via pytest-flake8
+furo==2021.2.28b28
+    # via -r dev-requirements.in
+idna==2.10
+    # via
+    #   requests
+    #   yarl
+imagesize==1.2.0
+    # via sphinx
+isort==5.7.0
+    # via pytest-isort
+jinja2==2.11.2
+    # via sphinx
+markupsafe==1.1.1
+    # via jinja2
+mccabe==0.6.1
+    # via flake8
+more-itertools==8.6.0
+    # via pytest
+multidict==5.1.0
+    # via yarl
+mypy-extensions==0.4.3
+    # via mypy
+mypy==0.790
+    # via pytest-mypy
+packaging==20.8
+    # via
+    #   pytest
+    #   sphinx
+pip-tools==5.5.0
+    # via -r dev-requirements.in
+pluggy==0.13.1
+    # via pytest
+py==1.10.0
+    # via pytest
+pycodestyle==2.6.0
+    # via flake8
+pyflakes==2.2.0
+    # via flake8
+pygments==2.7.3
+    # via sphinx
+pyparsing==2.4.7
+    # via packaging
+pytest-cov==2.8.1
+    # via -r dev-requirements.in
+pytest-env==0.6.2
+    # via -r dev-requirements.in
+pytest-flake8==1.0.7
+    # via -r dev-requirements.in
+pytest-isort==1.2.0
+    # via -r dev-requirements.in
+pytest-mypy==0.5.0
+    # via -r dev-requirements.in
+pytest-vcr==1.0.2
+    # via -r dev-requirements.in
+pytest==5.3.5
+    # via
+    #   -r dev-requirements.in
+    #   pytest-cov
+    #   pytest-env
+    #   pytest-flake8
+    #   pytest-mypy
+    #   pytest-vcr
+pytz==2020.5
+    # via babel
+pyyaml==5.3.1
+    # via vcrpy
+recommonmark==0.7.1
+    # via -r dev-requirements.in
+requests==2.25.1
+    # via sphinx
+six==1.15.0
+    # via vcrpy
+snowballstemmer==2.0.0
+    # via sphinx
+soupsieve==2.2
+    # via beautifulsoup4
+sphinx-autodoc-typehints[type_comments]==1.11.1
+    # via -r dev-requirements.in
+sphinx==3.4.2
+    # via
+    #   -r dev-requirements.in
+    #   furo
+    #   recommonmark
+    #   sphinx-autodoc-typehints
+sphinxcontrib-applehelp==1.0.2
+    # via sphinx
+sphinxcontrib-devhelp==1.0.2
+    # via sphinx
+sphinxcontrib-htmlhelp==1.0.3
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.3
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.4
+    # via sphinx
+typed-ast==1.4.2
+    # via mypy
+typing-extensions==3.7.4.3
+    # via mypy
+urllib3==1.26.2
+    # via requests
+vcrpy==4.1.1
+    # via pytest-vcr
+wcwidth==0.2.5
+    # via pytest
+wrapt==1.12.1
+    # via vcrpy
+yarl==1.6.3
+    # via vcrpy
 
 # The following packages are considered to be unsafe in a requirements file:
 # pip

docs/source/auth-providers.md

@@ -13,9 +13,10 @@ validating the identity of the entity (person or machine) sending a request to G
 identity has been established, whether the requesting party is permitted to perform 
 the requested operation 
 
-**NOTE**: In this guide and elsewhere we may refer to `auth` as a way of referring to 
-both authentication and authorization in general, or where distinction between the two
-concepts is not important. 
+``` note:: In this guide and elsewhere we may refer to *auth* as a way of referring to 
+   both authentication and authorization in general, or where distinction between the two
+   concepts is not important.
+```
 
 ## Provided Auth Modules
 Giftless provides the following authentication and authorization modules by default:

docs/source/conf.py

@@ -14,6 +14,7 @@
 # import sys
 # sys.path.insert(0, os.path.abspath('.'))
 
+from recommonmark.transform import AutoStructify
 
 # -- Project information -----------------------------------------------------
 
@@ -34,6 +35,7 @@
 extensions = [
     'recommonmark',
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosectionlabel',
     'sphinx_autodoc_typehints'
 ]
 
@@ -51,9 +53,22 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-html_theme = 'alabaster'
+html_theme = 'furo'
 
 # 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 = ['_static']
+
+
+# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
+# rather than 'path/to/file:heading'
+autosectionlabel_prefix_document = True
+
+
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+        'known_url_schemes': ['http', 'https', 'mailto'],
+        'auto_toc_tree_section': 'Contents',
+    }, True)
+    app.add_transform(AutoStructify)

docs/source/guides.rst

@@ -5,8 +5,7 @@ This section includes several how-to guides designed to get you started with Gif
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
 
-   installation
    quickstart
    using-gcs
+   jwt-auth-guide

docs/source/index.rst

@@ -13,15 +13,14 @@ methods and authentication methods.
    :maxdepth: 2
    :caption: Contents:
 
+   installation
    guides
    configuration
    components
    development
    api
 
-Indices and tables
-==================
-
+Indices and Tables
+------------------
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

docs/source/installation.md

@@ -1,35 +1,41 @@
-Installation
-============
+Installation / Deployment
+=========================
 
 You can install and run Giftless in different ways, depending on your needs:
 
-## Running from a Docker image
+## Running from Docker image
 Giftless is available as a Docker image available from 
 [Docker Hub](https://hub.docker.com/r/datopian/giftless) 
 
 To run the latest version of Giftless in HTTP mode, listening
 on port 8080, run:
 
-    $ docker run --rm -p 8080:8080 datopian/giftless \
-        -M -T --threads 2 -p 2 --manage-script-name --callable app \
-        --http 0.0.0.0:8080
+```
+$ docker run --rm -p 8080:8080 datopian/giftless \
+    -M -T --threads 2 -p 2 --manage-script-name --callable app \
+    --http 0.0.0.0:8080
+```
 
 This will pull the image and run it. 
 
 Alternatively, to run in `WSGI` mode you can run:
 
-    $ docker run --rm -p 5000:5000 datopian/giftless
+```
+$ docker run --rm -p 5000:5000 datopian/giftless
+```
 
 This will require an HTTP server such as *nginx* to proxy HTTP requests to it.
 
 If you need to, you can also build the Docker image locally as described below.
 
-## Installing & Running from Pypi
+## Running from Pypi package
 You can install Giftless into your Python environment of choice (3.7+) using pip. 
 It is recommended to install Giftless into a virtual environment:
 
-    (venv) $ pip install uwsgi
-    (venv) $ pip install giftless
+```shell
+(venv) $ pip install uwsgi
+(venv) $ pip install giftless
+```
 
 **IMPORTANT**: as of the time of writing, a bug in one of Giftless' dependencies
 requires that you explicitly install dependencies after installing using `pip`:
@@ -38,24 +44,28 @@ requires that you explicitly install dependencies after installing using `pip`:
 
 Once installed, you can run Giftless locally with uWSGI:
 
-    # Run uWSGI (see uWSGI's manual for help on all arguments)
-    (venv) $ uwsgi -M -T --threads 2 -p 2 --manage-script-name \
-        --module giftless.wsgi_entrypoint --callable app --http 127.0.0.1:8080
+```
+# Run uWSGI (see uWSGI's manual for help on all arguments)
+(venv) $ uwsgi -M -T --threads 2 -p 2 --manage-script-name \
+    --module giftless.wsgi_entrypoint --callable app --http 127.0.0.1:8080
+```
 
 This will listen on port `8080`.
 
-You shoud be able to replace `uwsgi` with any other WSGI server, such as `gunicorn`.
+You should be able to replace `uwsgi` with any other WSGI server, such as `gunicorn`.
 
-## Installing & Running from Source
+## Running from source installation
 You can install and run `giftless` from source:
 
-    $ git clone https://github.com/datopian/giftless.git
+```shell
+$ git clone https://github.com/datopian/giftless.git
 
-    # Initialize a virtual environment
-    $ cd giftless
-    $ python3 -m venv venv
-    $ source venv/bin/activate
-    (venv) $ pip install -r requirements.txt
+# Initialize a virtual environment
+$ cd giftless
+$ python3 -m venv venv
+$ source venv/bin/activate
+(venv) $ pip install -r requirements.txt
+```
 
 You can then proceed to run Giftless with a WSGI server as
 described above.
@@ -64,6 +74,8 @@ Note that for non-production use you may avoid using a WSGI server and rely
 on Flask's built in development server. This should **never** be done in a
 production environment:
 
-    (venv) $ ./flask-develop.sh
+```shell
+(venv) $ ./flask-develop.sh
+```
 
 In development mode, Giftless will be listening on <http://127.0.0.1:5000/>