Merge pull request #5 from djpugh/feature/config-docs

.github/workflows/pipeline.yml

@@ -21,6 +21,34 @@ jobs:
           pip install tox
       - name: Lint
         run: tox -e lint
+
+  security:
+    name: Security Lint
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+      - name: Lint with Bandit
+        run: tox -e security
+
+  types:
+    name: Check Types
+    runs-on: windows-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python
+        uses: actions/setup-python@v2
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+      - name: Check Types
+        run: tox -e types
 
   test:
     name: Test Python ${{ matrix.py }} - ${{ matrix.os }}
@@ -200,13 +228,15 @@ jobs:
           pip install -r ./repo/requirements.txt
           pip install -U tox pytest setuptools
       - shell: bash
-        run: pytest ./repo/tests/functional
+        run: pytest ./repo/tests/unit
 
   automerge:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     needs: 
       - lint
+      - security
+      - types
       - test
       - build
       - license-scan
@@ -230,6 +260,8 @@ jobs:
     runs-on: ubuntu-latest
     needs: 
       - lint
+      - security
+      - types
       - test
       - build
       - sonarcloud

.gitignore

@@ -24,4 +24,8 @@ reports/*-py*
 .coverage
 reports/*
 *.c
-.env
+.env
+.vscode
+reports/*
+test-reports/*
+Pipfile

MANIFEST.in

@@ -1,4 +1,7 @@
 include requirements.txt
 include versioneer.py
 include src/fastapi_aad_auth/_version.py
-include src/*.html
+include *.html
+include *.css
+include *.css.map
+include *.png

README.rst

@@ -39,15 +39,17 @@ fastapi_aad_auth
     :target: https://github.com/djpugh/fastapi_aad_auth/pulls
 
 
-Adding Azure Active Directory Authentication for FastAPI
+Add Azure Active Directory Authentication for FastAPI, including for REST API Documentation
 
 
 Links
 -----
 
 * `Full Documentation <https://djpugh.github.io/fastapi_aad_auth>`_
 * `Installation <https://djpugh.github.io/fastapi_aad_auth/installation.html>`_
+* `Configuring FastAPI to use AAD Auth <https://djpugh.github.io/fastapi_aad_auth/usage.html>`_
 * `Changelog <https://djpugh.github.io/fastapi_aad_auth/changelog.html>`_
+* `Contributing <https://djpugh.github.io/fastapi_aad_auth/development.html>`_
 * `Issues <https://github.com/djpugh/fastapi_aad_auth/issues>`_
 * `PyPI <https://pypi.org/project/fastapi_aad_auth>`_
 * |github| `Github <https://github.com/djpugh/fastapi_aad_auth>`_
@@ -56,71 +58,6 @@ Links
     :target: https://github.com/djpugh/fastapi_aad_auth
 
 
-Using it
---------
-
-The configuration is defined in ``src/fastapi_aad_auth/config.py``, and includes options for configuring
-the AAD config, the login UI and the routes.
-
-You can initialise it with::
-
-    from fastapi_aad_auth import AADAuth, AuthenticationState, Config
-    auth_provider = AADAuth()
-
-    # If you had a config that wasn't set in the environment, you could use 
-    # auth_provider = AADAuth(Config(<my config kwargs>)
-
-
-You can use it for fastapi routes::
-
-    from fastapi import APIRouter, Depends
-
-
-    # Use the auth_provider.api_auth_scheme for fastapi authentication
-
-    router = APIRouter()
-
-    @router.get('/hello')
-    async def hello_world(auth_state: AuthenticationState =D epends(auth_provider.api_auth_scheme)):
-        print(auth_state)
-        return {'hello': 'world'}
-
-For starlette routes (i.e. interactive/HTML pages), use the auth_provider.auth_required for authentication::
-
-    from starlette.responses import PlainTextResponse
-
-    @auth_provider.auth_required()
-    async def test(request):
-        if request.user.is_authenticated:
-            return PlainTextResponse('Hello, ' + request.user.display_name)
-
-This middleware will set the request.user object and request.credentials object::
-
-    async def homepage(request):
-        if request.user.is_authenticated:
-            return PlainTextResponse('Hello, ' + request.user.display_name)
-        return PlainTextResponse(f'Hello, you')
-
-
-You can set the swagger_ui_init_oauth using auth_provider.api_auth_scheme.init_oauth::
-
-    from fastapi import FastAPI
-    app = FastAPI(title='fastapi_aad_auth test app',
-                  description='Adding Azure Active Directory Authentication for FastAPI',
-                  version='0.1.0',
-                  openapi_url=f"/api/v0/openapi.json",
-                  docs_url='/api/docs',
-                  swagger_ui_init_oauth=auth_provider.api_auth_scheme.init_oauth,
-                  redoc_url='/api/redoc',
-                  routes=routes)
-
-
-To add the required middleware to the fastapi app use::
-
-    auth_provider.configure_app(app)
-
-
-
 Coverage
 ~~~~~~~~
 

docs/source/conf.py

@@ -37,6 +37,7 @@
     'sphinx.ext.napoleon',
     'sphinx.ext.intersphinx',
     'sphinx.ext.mathjax',
+    'sphinx.ext.extlinks',
     'sphinx.ext.todo',
     'sphinx.ext.ifconfig',
     'sphinx.ext.viewcode',
@@ -64,7 +65,7 @@
 
 # General information about the project.
 project = u'fastapi-aad-auth'
-copyright = str(dt.datetime.now().year)+__author__
+copyright = str(dt.datetime.now().year)+' '+__author__
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

docs/source/config.rst

@@ -0,0 +1,6 @@
+Configuration Options
+*********************
+
+.. automodule:: fastapi_aad_auth.config
+    :members:
+    :exclude-members: bool_from_env,list_from_env

docs/source/development.rst

@@ -0,0 +1,135 @@
+Development
+===========
+
+Getting started
+---------------
+
+
+``fastapi_aad_auth`` is a volunteer maintained open source project and we welcome contributions of all forms. The sections
+below will help you get started with development, testing, and documentation. We’re pleased that you are interested in
+working on ``fastapi_aad_auth``. This document is meant to get you setup to work on ``fastapi_aad_auth`` and to act as a guide and reference
+to the development setup. If you face any issues during this process, please
+`open an issue <https://github.com/djpugh/fastapi_aad_auth/issues/new?title=Trouble+with+development+environment>`_ about it on
+the issue tracker.
+
+Setup
+~~~~~
+
+``fastapi_aad_auth`` is an extension component to :pypi:`fastapi` to provide Azure Active Directory authentication,
+written in Python. To work on it, you'll need:
+
+- **Source code**: available on `GitHub <https://github.com/djpugh/fastapi_aad_auth>`_. You can use ``git`` to clone the
+    repository:
+
+  .. code-block:: console
+
+      git clone https://github.com/djpugh/fastapi_aad_auth
+      cd fastapi_aad_auth
+
+- **Python interpreter**: We recommend using ``CPython``. You can use
+  `this guide <https://realpython.com/installing-python/>`_ to set it up.
+
+- :pypi:`tox`: to automatically get the projects development dependencies and run the test suite.
+
+- **Azure Active Directory App Registration**: We recommend following the configuration section in usage
+
+
+Running tests
+~~~~~~~~~~~~~
+
+``fastapi_aad_auth`` tests are written using the :pypi:`pytest` test framework. :pypi:`tox` is used to automate the setup
+and execution of ``fastapi_aad_auth`` tests.
+
+To run tests locally execute:
+
+.. code-block:: console
+
+    tox -e test
+
+This will run the test suite for the same Python version as under which ``tox`` is installed.
+
+Integration tests
+~~~~~~~~~~~~~~~~~
+
+``fastapi_aad_auth`` is very tightly coupled to Azure Active Directory, so most of the full tests follow manual testing
+of the testapp. This needs configuring with Azure Active Directory App Registrations (see :ref:`config-aad-appreg`) and
+the testapp environment using a ``.env`` file (see :ref:`config-fastapi_aad_auth-env`).
+
+To run the testapp use tox (or directly with ``python tests/testapp/server.py``:
+
+.. code-block:: console
+
+    tox -e testapp
+
+This will run the test suite for the same Python version as under which ``tox`` is installed.
+
+
+Configuring the testApp
+#######################
+
+
+
+
+Running linters
+~~~~~~~~~~~~~~~
+
+``fastapi_aad_auth`` uses :pypi:`flake8` and extensions for managing linting of the codebase. ``flake8`` performs various checks on all
+files in ``fastapi_aad_auth`` and uses tools that help follow a consistent code style within the codebase. To use linters locally,
+run:
+
+.. code-block:: console
+
+    tox -e lint
+
+.. note::
+
+    Avoid using ``# noqa`` comments to suppress linter warnings - wherever possible, warnings should be fixed instead.
+    ``# noqa`` comments are reserved for rare cases where the recommended style causes severe readability problems.
+
+Building documentation
+~~~~~~~~~~~~~~~~~~~~~~
+
+``fastapi_aad_auth`` documentation is built using :pypi:`Sphinx`. The documentation is written in reStructuredText. To build it
+locally, run:
+
+.. code-block:: console
+
+    tox -e docs
+
+The built documentation can be found in the ``docs/html`` folder and may be viewed by opening ``index.html`` within
+that folder.
+
+Release
+~~~~~~~
+
+We release through GitHub using an automated process to collate and test the releases. 
+
+Contributing
+-------------
+
+Submitting pull requests
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Submit pull requests against the ``master`` branch, providing a good description of what you're doing and why. You must
+have legal permission to distribute any code you contribute to ``fastapi_aad_auth`` and it must be available under the MIT
+License. Provide tests that cover your changes and run the tests locally first. ``fastapi_aad_auth``
+:ref:`supports <compatibility-requirements>` multiple Python versions. Any pull request must
+consider and work on all these platforms.
+
+Pull Requests should be small to facilitate review. Keep them self-contained, and limited in scope. `Studies have shown
+<https://www.kessler.de/prd/smartbear/BestPracticesForPeerCodeReview.pdf>`_ that review quality falls off as patch size
+grows. Sometimes this will result in many small PRs to land a single large feature. In particular, pull requests must
+not be treated as "feature branches", with ongoing development work happening within the PR. Instead, the feature should
+be broken up into smaller, independent parts which can be reviewed and merged individually.
+
+Additionally, avoid including "cosmetic" changes to code that is unrelated to your change, as these make reviewing the
+PR more difficult. Examples include re-flowing text in comments or documentation, or addition or removal of blank lines
+or whitespace within lines. Such changes can be made separately, as a "formatting cleanup" PR, if needed.
+
+Automated testing
+~~~~~~~~~~~~~~~~~
+
+All pull requests and merges to ``master`` branch are tested using
+Github actions (configured by ``.github/workflows/pipeline.yml`` file. You can find the status and results to the CI runs for your
+PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages for the specific builds in
+the form of "Details" links, in case the CI run fails and you wish to view the output.

docs/source/index.rst

@@ -38,11 +38,21 @@ fastapi-aad-auth
 .. image:: https://img.shields.io/github/issues-pr-raw/djpugh/fastapi_aad_auth
     :target: https://github.com/djpugh/fastapi_aad_auth/pulls
 
+Provide Azure Active Directory Authentication for both the API and associated interactive pages (documents, openapi etc).
+
+The repository is open source (MIT Licensed) on |github| `Github <https://github.com/djpugh/fastapi_aad_auth>`_
+
+.. |github| image:: https://api.iconify.design/logos-github-icon.svg
+    :target: https://github.com/djpugh/fastapi_aad_auth
+
+
 .. toctree::
     :maxdepth: 1
 
     Release Information <changelog>
-
+    Usage <usage>
+    Configuration Options <config>
+    Contributing <development>
 
 
 ---------------------------------------