documentation improvements (relates to #332 and #341)

CHANGES.rst

@@ -1,7 +1,8 @@
+.. explicit references must be used in this file (not references.rst) to ensure they are directly rendered on Github
 .. :changelog:
 
 Changes
-=======
+*******
 
 `Unreleased <https://github.com/Ouranosinc/Magpie/tree/master>`_ (latest)
 ------------------------------------------------------------------------------------
@@ -31,7 +32,7 @@ Features / Changes
   specified with ``MAGPIE_CONFIG_PATH`` environment variable or ``magpie.config_path`` setting (example in ``configs``).
 * Add configurable user creation parameters upon `Magpie` application startup through configuration files
   (fixes `#47 <https://github.com/Ouranosinc/Magpie/issues/47>`_ and
-   `#204 <https://github.com/Ouranosinc/Magpie/issues/204>`_).
+  `#204 <https://github.com/Ouranosinc/Magpie/issues/204>`_).
 * Add disabled checkboxes for UI rendering of non-editable items
   (relates to `#164 <https://github.com/Ouranosinc/Magpie/issues/164>`_).
 * Add more tests to validate forbidden operations such as update or delete of reserved user and group details.
@@ -49,6 +50,9 @@ Features / Changes
 * Add support of new response content-type as XML.
 * Add support of ``Accept`` header and ``format`` query parameter for all API responses, for content-types variations
   in either plain text, HTML, XML or JSON (default), and include applicable values in schemas for Swagger generation.
+* Add documentation details about different types of ``Permission``, interaction between various `Magpie` models,
+  glossary and other general improvements (relates to `#332 <https://github.com/Ouranosinc/Magpie/issues/332>`_ and
+  `#341 <https://github.com/Ouranosinc/Magpie/issues/341>`_).
 
 Bug Fixes
 ~~~~~~~~~~~~~~~~~~~~~

Makefile

@@ -188,7 +188,7 @@ docs-show: $(DOC_LOCATION)	## display HTML webpage of generated documentation (b
 	@-test -f "$(DOC_LOCATION)" || $(MAKE) -C "$(APP_ROOT)" docs
 	$(BROWSER) "$(DOC_LOCATION)"
 
-## --- Versionning targets --- ##
+## --- Versioning targets --- ##
 
 # Bumpversion 'dry' config
 # if 'dry' is specified as target, any bumpversion call using 'BUMP_XARGS' will not apply changes

README.rst

@@ -1,3 +1,5 @@
+.. explicit references must be used in this file (not references.rst) to ensure they are directly rendered on Github
+
 ======================================
 Magpie: A RestFul AuthN/AuthZ service
 ======================================
@@ -69,9 +71,9 @@ Behind the scene, it uses `Ziggurat-Foundations`_ and `Authomatic`_.
 
 .. end-badges
 
-
+--------------
 Documentation
-=============
+--------------
 
 The REST API documentation is auto-generated and served under ``{MAGPIE_URL}/api/`` using Swagger-UI with tag ``latest``.
 
@@ -81,8 +83,9 @@ The REST API documentation is auto-generated and served under ``{MAGPIE_URL}/api
 .. _readthedocs: https://pavics-magpie.readthedocs.io
 .. _docs: https://github.com/Ouranosinc/Magpie/tree/master/docs
 
+----------------------------
 Configuration and Usage
-=======================
+----------------------------
 
 | Multiple configuration options exist for ``Magpie`` application.
 | Please refer to `configuration`_ for details.
@@ -91,16 +94,17 @@ Configuration and Usage
 .. _configuration: ./docs/configuration.rst
 .. _usage: ./docs/usage.rst
 
-
+--------------
 Change History
-==============
+--------------
 
 Addressed features, changes and bug fixes per version tag are available in `changes`_.
 
 .. _changes: CHANGES.rst
 
+--------------
 Docker Images
-=============
+--------------
 
 Following most recent variants are available:
 
@@ -126,6 +130,7 @@ Following most recent variants are available:
 - `Twitcher`_ image with integrated ``MagpieAdapter`` are only available for Magpie ``>=1.0.0``
 
 .. REST API redoc reference is auto-generated by sphinx from magpie cornice-swagger definitions
+.. These reference must be left direct (not included) to allow pretty rendering on Github
 .. _REST API: https://pavics-magpie.readthedocs.io/en/latest/api.html
 .. _Authomatic: https://authomatic.github.io/authomatic/
 .. _PostgreSQL: https://www.postgresql.org/

SECURITY.rst

@@ -1,14 +1,15 @@
+***************
 Security Policy
-===============
+***************
 
 Supported Versions
-~~~~~~~~~~~~~~~~~~
+=====================
 
 This project supports only the latest tagged version as it is constantly evolving.
 Make sure you are using the latest available version to receive latest vulnerability patches if any.
 
 Reporting a Vulnerability
-~~~~~~~~~~~~~~~~~~~~~~~~~
+==========================
 
 Please submit a new issue with the tag `security` and detail it so we can reproduce it and work on it.
 

docs/Makefile

@@ -9,7 +9,11 @@ BUILDDIR      = _build
 
 # User-friendly check for sphinx-build
 ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
-$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
+$(error "The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD " \
+		"environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can " \
+		"add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from " \
+		"http://sphinx-doc.org/" \
+)
 endif
 
 # Internal variables.

docs/_static/.gitignore

@@ -1,3 +1,4 @@
 # make this directory available as it is referenced by some extensions
 *.*
 !.gitignore
+!custom.css

docs/_static/custom.css

@@ -0,0 +1,6 @@
+div.body p, div.body dd, div.body li, div.body blockquote {
+    -moz-hyphens: none;
+    -ms-hyphens: none;
+    -webkit-hyphens: none;
+    hyphens: none;
+}

docs/conf.py

@@ -94,7 +94,7 @@ def doc_redirect_include(file_path):
 
 redoc = [{
     "name": __meta__.__title__,
-    "page": "api",  # rendered under '{root}/api.html'
+    "page": "api",  # rendered under "{root}/api.html"
     "spec": api_spec_file,
     "embed": True,
     "opts": {
@@ -161,7 +161,7 @@ def doc_redirect_include(file_path):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = ["_build"]
+exclude_patterns = []
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.
@@ -198,7 +198,9 @@ def doc_redirect_include(file_path):
 # Theme options are theme-specific and customize the look and feel of a
 # theme further.  For a list of options available for each theme, see the
 # documentation.
-# html_theme_options = {}
+html_theme_options = {
+    "navigation_depth": 3,  # TOC, RTD theme
+}
 
 # Add any paths that contain custom themes here, relative to this directory.
 # html_theme_path = []
@@ -224,15 +226,16 @@ def doc_redirect_include(file_path):
 # 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_css_files = ["custom.css"]
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
 # html_extra_path = []
 
-# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
+# If not "", a "Last updated on:" timestamp is inserted at every page bottom,
 # using the given strftime format.
-# html_last_updated_fmt = '%b %d, %Y'
+html_last_updated_fmt = "%Y-%m-%d"
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
@@ -297,7 +300,7 @@ def doc_redirect_include(file_path):
 # (source start file, target name, title,
 #  author, documentclass [howto, manual, or own class]).
 latex_documents = [
-    ("index", "{}.tex".format(__meta__.__package__), doc_title, __meta__.__author__, "manual"),
+    (master_doc, "{}.tex".format(__meta__.__package__), doc_title, __meta__.__author__, "manual"),
 ]
 
 # The name of an image file (relative to this directory) to place at
@@ -326,7 +329,7 @@ def doc_redirect_include(file_path):
 # One entry per manual page. List of tuples
 # (source start file, name, description, authors, manual section).
 man_pages = [
-    ("index", __meta__.__package__, doc_title, [__meta__.__author__], 1)
+    (master_doc, __meta__.__package__, doc_title, [__meta__.__author__], 1)
 ]
 
 # If true, show URL addresses after external links.
@@ -339,7 +342,7 @@ def doc_redirect_include(file_path):
 # (source start file, target name, title, author,
 #  dir menu entry, description, category)
 texinfo_documents = [
-    ("index", __meta__.__package__,
+    (master_doc, __meta__.__package__,
      doc_title,
      __meta__.__author__,
      __meta__.__package__,

docs/glossary.rst

@@ -0,0 +1,93 @@
+.. _glossary:
+.. include:: references.rst
+
+************
+Glossary
+************
+
+.. glossary::
+    :sorted:
+
+    ACL
+        Access Control List.
+        Set of :term:`User` and :term:`Group` scopes, provided session :term:`Authentication` elements, that either
+        grants or denies access to the applicable :term:`User` to the targeted HTTP request.
+
+    Authentication
+        Process of identifying one-self using credentials in order to login into `Magpie`, or retrieving connected
+        session :term:`User` during an HTTP request using supported methods.
+
+    Authorization
+        Process of allowing or denying access to a :term:`Resource` or :term:`Service` according to :term:`Logged User`
+        identified through :term:`Authentication` methods. This process typically falls into the hands of a
+        :term:`Proxy` application.
+
+    Cookies
+        Set of :term:`Authentication` identifiers primarily employed by `Magpie` HTTP requests to determine the
+        :term:`Logged User`.
+
+    Direct Permission
+        Describes a :term:`Permission` that originates directly from a :term:`Service`.
+        See :ref:`direct permissions` details.
+
+    Discoverable Group
+        :term:`Group` that has property ``discoverable=True``, making it publicly viewable to any-level user.
+        Otherwise, groups can be listed or accessed only by administrators.
+
+    Effective Permission
+        A :term:`Permission` that has been completely resolved according to all applicable contexts, that indicates
+        the final granted or denied result. See also :ref:`effective permissions`.
+
+    Group
+        Entity on which :term:`Permission` over a :term:`Service` or :term:`Resource` can be applied. Any :term:`User`
+        can be set as a member of any number of :term:`Group`, making it inherit all applicable set of
+        :term:`Permission`.
+
+    Inherited Permission
+        Describes a :term:`Permission` that originates from a children :term:`Resource` under a :term:`Service`.
+        See :ref:`inherited permissions` details.
+
+    Logged User
+        Specific :term:`User` that corresponds to the active request session. This :term:`User` can automatically be
+        referenced to (instead of usual ``{user_name}`` path variable) in applicable requests using special value
+        configured with :py:data:`magpie.constants.MAGPIE_LOGGED_USER`. When not logged in, this
+        :term:`User` is considered to be :py:data:`magpie.constants.MAGPIE_ANONYMOUS_USER`. Otherwise, it is whoever
+        the :term:`Authentication` mechanism identifies.
+
+    Permission
+        Element that defines which rules are applicable for a given combination of :term:`User` and/or :term:`Group`
+        against one or many :term:`Service` and/or :term:`Resource`. See `permissions`_ for more exhaustive details.
+        Applicable values defined by enum :py:class:`magpie.permissions.Permission`.
+
+    Proxy
+        Sibling service (typically `Twitcher <Twitcher>`_) that employs `Magpie` as access management of :term:`User`,
+        :term:`Group`, :term:`Service` and :term:`Resource` to obtain applicable sets of :term:`Permission`.
+        Provided these, it acts as policy enforcement point (PEP).
+
+    Public
+        Refers to a :term:`Permission` applied on a :term:`Service` or :term:`Resource` to special elements in order
+        to make them available to anyone including even unauthenticated sessions. See also :ref:`Public Access` section
+        for implementation details to achieve this result.
+
+    Resource
+        Entity on which :term:`User` and :term:`Group` can be associated to applicable :term:`Permission` respectively
+        for the contextual :term:`Service` under which it resides. This element can represent relatively *anything*.
+        The interpretation of each :term:`Resource` depends on the context of the :term:`Service` they relate to.
+        Implemented by sub-classes of :py:class:`magpie.models.Resource`.
+
+    Service
+        Top-level specialized :term:`Resource` that defines which children :term:`Resource` elements are applicable to
+        it (if any), how its hierarchy of :term:`Resource` should behave against incoming HTTP request details, and how
+        to parse any set of :term:`Permission` applied on them against respective request elements. Also defines URL
+        connexion details pointing to the actual service on which access control are applicable. Each type of
+        :term:`Service` defines different combination of functionalities. Implemented by sub-classes of
+        :py:class:`magpie.models.ServiceInterface`.
+
+    User
+        Unitary entity containing details about the user allowing it to log into `Magpie` and that can have other
+        relationships applied to it such as :term:`Permission` and :term:`Group` that extend his specific access rights
+        to :term:`Service` and :term:`Resource` elements. Implemented by :py:class:`magpie.models.User`.
+
+
+.. _permissions: permissions.rst
+

docs/index.rst

@@ -1,36 +1,11 @@
-Magpie Documentation
-======================================
-
 .. include:: ../README.rst
-
-Package Information
-===================
-
-.. toctree::
-   :maxdepth: 2
-
-   usage
-   installation
-   configuration
-   utilities
-   performance
-   contributing
-   authors
-   changes
-   security
-
-
-Source Code
-===================
-
-.. toctree::
-   :maxdepth: 2
+.. include:: toc.rst
 
 
+----------------------------
 Indices and Tables
-==================
+----------------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/installation.rst

@@ -1,5 +1,9 @@
+.. _installation:
+.. include:: references.rst
+
+************
 Installation
-============
+************
 
 At the command line::
 

docs/performance.rst

@@ -1,9 +1,12 @@
-===========
+.. _performance:
+.. include:: references.rst
+
+*************
 Performance
-===========
+*************
 
 Requesting permissions for a specific user and service can be demanding if a lot of
-requests are done rapidly. PostgreSQL and sqlalchemy are usually fast enough, but
+requests are done rapidly. `PostgreSQL`_ and `SQLAlchemy`_ are usually fast enough, but
 when more than a couple requests per second are needed, some solutions are possible to
 improve the performance of these requests.