Merge pull request #22 from makinacorpus/update_doc_2

Fix broken documentation links

Author: gbip

README.md

@@ -28,13 +28,13 @@ If you are not satisfied with the default configuration, take a look at the cook
 
 ## Features
 
-- Easy configuration through premade [`Provider`](https://django-pyoidc.readthedocs.io/latest/reference.html#providers) classes.
+- Easy configuration through premade `Provider` classes (see the list [here](https://django-pyoidc.readthedocs.io/latest/reference.html#providers)
 - Authenticate users from multiple providers
 - Bearer authentication support for [django-rest-framework](https://www.django-rest-framework.org/) integration (**single provider**)
 - Easy integration with the [Django permission system](https://django-pyoidc.readthedocs.io/latest/how-to.html#use-the-django-permission-system-with-oidc)
 - Highly customizable design that should suit most needs
 - Support back-channel logout
-- Support service accounts (accounts for machine-to-machine uses)
+- Support service accounts (accounts for machine-to-machine authentication)
 - Sane and secure defaults settings
 
 ## Roadmap

docs/explanation.rst

@@ -1,3 +1,5 @@
+.. _expl_new_oidc:
+
 Why make a new OIDC library ?
 =============================
 
@@ -16,7 +18,8 @@ Here are our criteria :
 `django-allauth <https://github.com/pennersr/django-allauth/>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Todo**
+This library OIDC implementation is based on the python package ``oic`` which we believe should not
+be used for OIDC usages.
 
 `django-auth-oidc <https://gitlab.com/aiakos/django-auth-oidc>`_
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -302,6 +305,8 @@ Note: if your Django acts as an OIDC SSO server for other applications, receivin
 containing an iframe with front channel logouts links for all the client applications of your Django. In this library we consider the
 Django website to be only an OIDC client (not server) and we did not implement this cascading front channel logout specification.
 
+.. _expl_cache:
+
 About caching
 =============
 

docs/how-to.rst

@@ -55,7 +55,7 @@ Here is how it looks if we extend the configuration made in :ref:`Configure the
         },
 
 
-See :ref:`Hook settings` for more information on the function path syntax.
+See :ref:`Hook settings <settings_hook>` for more information on the function path syntax.
 
 You should now see a message on login/logout ! 🎉
 
@@ -136,7 +136,7 @@ group named *admin*. If you are not familiar with the claims available in your t
 
 To have this function called instead of the default one, you need to modify your settings so that :ref:`hook_get_user` points to the function that we just wrote.
 
-The value of this setting should be : ``<my_app>.oidc:login_function`` (see :ref:`Hook settings` for more information on this syntax).
+The value of this setting should be : ``<my_app>.oidc:login_function`` (see :ref:`Hook settings <settings_hook>` for more information on this syntax).
 
 If you configured your settings manually (without using the providers system), you can add the key directly.
 
@@ -267,11 +267,9 @@ TODO: RedirectDemo now exists, where do I connect it?
 Use multiple identity providers
 ===============================
 
-**TODO**
-
 This library natively supports multiples identity providers.
 
-You already have to specify a provider name when you configure your settings (either automatically by using a provider, or :ref:`manually <Providers settings>`).
+You already have to specify a provider name when you configure your settings (either automatically by using a provider, or :ref:`manually <provider-class-setting>`).
 
 In a multi-provider setup, the settings look like this :
 

docs/reference.rst

@@ -42,8 +42,11 @@ Providers classes allows the final user to configure their project without havin
 Each provider implements the configuration logic and should be used using the :ref:`provider-class-setting` setting.
 
 .. tip::
+    Read :ref:`the tutorial <tuto_settings>` to learn how to use provider class !
 
-    All the named arguments of __init__() can be set by configuring a setting **with the same**.
+.. tip::
+
+    All the named arguments of __init__() can be set by configuring a setting **with the same name**.
 
 Provider list
 ^^^^^^^^^^^^^

docs/settings.rst

@@ -163,7 +163,9 @@ cache_django_backend
 
 This setting configures the cache backend that is used to store OIDC sessions details. It should be
 the name of a cache defined in the ``CACHES` django settings.
-You can read more about *Cache Management* :ref:`here <Cache Management>`.
+You can read more about *Cache Management* :ref:`here <expl_cache>`.
+
+.. _settings_hook:
 
 Hook
 ====

docs/tutorial.rst

@@ -113,7 +113,7 @@ Configure a cache backend
 *************************
 
 **You must have a cache backend** for this library to work ! The OIDC protocol is very statefull and we use Django cache system to store data.
-If you want to understand why, you can read the :ref:`Cache Management` page.
+If you want to understand why, you can read the :ref:`Cache management <expl_cache>` page.
 
 For the sake of this tutorial, you can use this cache management snippet (it should be pasted in your ``settings.py``) :
 
@@ -129,6 +129,8 @@ For the sake of this tutorial, you can use this cache management snippet (it sho
 .. warning::
     Do not use those settings in production ! Go read the `django documentation <https://docs.djangoproject.com/en/stable/topics/cache/#setting-up-the-cache>`_ for more details.
 
+.. _tuto_settings:
+
 Configure the library
 *********************
 
@@ -216,6 +218,8 @@ This will create 4 views in your URL configuration. They all have a name that de
 
 You should now be able to use the view names from this library to redirect the user to a login/logout page.
 
+.. _drf_tuto:
+
 Configuring django_rest_framework
 =================================