docs: clean up and improve documentation (#1401)

docs/advanced_topics.rst

@@ -31,7 +31,7 @@ Django OAuth Toolkit lets you extend the AbstractApplication model in a fashion
 custom user models.
 
 If you need, let's say, application logo and user agreement acceptance field, you can do this in
-your Django app (provided that your app is in the list of the INSTALLED_APPS in your settings
+your Django app (provided that your app is in the list of the ``INSTALLED_APPS`` in your settings
 module)::
 
     from django.db import models
@@ -44,11 +44,11 @@ module)::
 Then you need to tell Django OAuth Toolkit which model you want to use to represent applications.
 Write something like this in your settings module::
 
-    OAUTH2_PROVIDER_APPLICATION_MODEL='your_app_name.MyApplication'
+    OAUTH2_PROVIDER_APPLICATION_MODEL = 'your_app_name.MyApplication'
 
 Be aware that, when you intend to swap the application model, you should create and run the
-migration defining the swapped application model prior to setting OAUTH2_PROVIDER_APPLICATION_MODEL.
-You'll run into models.E022 in Core system checks if you don't get the order right.
+migration defining the swapped application model prior to setting ``OAUTH2_PROVIDER_APPLICATION_MODEL``.
+You'll run into ``models.E022`` in Core system checks if you don't get the order right.
 
 You can force your migration providing the custom model to run in the right order by
 adding::
@@ -61,15 +61,15 @@ to the migration class.
 
 That's all, now Django OAuth Toolkit will use your model wherever an Application instance is needed.
 
-    **Notice:** `OAUTH2_PROVIDER_APPLICATION_MODEL` is the only setting variable that is not namespaced, this
+.. note:: ``OAUTH2_PROVIDER_APPLICATION_MODEL`` is the only setting variable that is not namespaced, this
     is because of the way Django currently implements swappable models.
-    See issue #90 (https://github.com/jazzband/django-oauth-toolkit/issues/90) for details
+    See `issue #90 <https://github.com/jazzband/django-oauth-toolkit/issues/90>`_ for details.
 
 Multiple Grants
 ~~~~~~~~~~~~~~~
 
 The default application model supports a single OAuth grant (e.g. authorization code, client credentials). If you need
-applications to support multiple grants, override the `allows_grant_type` method. For example, if you want applications
+applications to support multiple grants, override the ``allows_grant_type`` method. For example, if you want applications
 to support the authorization code *and* client credentials grants, you might do the following::
 
     from oauth2_provider.models import AbstractApplication
@@ -86,12 +86,12 @@ Skip authorization form
 
 Depending on the OAuth2 flow in use and the access token policy, users might be prompted for the
 same authorization multiple times: sometimes this is acceptable or even desirable but other times it isn't.
-To control DOT behaviour you can use the `approval_prompt` parameter when hitting the authorization endpoint.
+To control DOT behaviour you can use the ``approval_prompt`` parameter when hitting the authorization endpoint.
 Possible values are:
 
-* `force` - users are always prompted for authorization.
+* ``force`` - users are always prompted for authorization.
 
-* `auto` - users are prompted only the first time, subsequent authorizations for the same application
+* ``auto`` - users are prompted only the first time, subsequent authorizations for the same application
   and scopes will be automatically accepted.
 
 Skip authorization completely for trusted applications
@@ -109,7 +109,7 @@ Overriding views
 ================
 
 You may want to override whole views from Django OAuth Toolkit, for instance if you want to
-change the login view for unregistred users depending on some query params.
+change the login view for unregistered users depending on some query params.
 
 In order to do that, you need to write a custom urlpatterns
 

docs/contributing.rst

@@ -12,7 +12,7 @@ This is a `Jazzband <https://jazzband.co>`_ project. By contributing you agree t
 Setup
 =====
 
-Fork `django-oauth-toolkit` repository on `GitHub <https://github.com/jazzband/django-oauth-toolkit>`_ and follow these steps:
+Fork ``django-oauth-toolkit`` repository on `GitHub <https://github.com/jazzband/django-oauth-toolkit>`_ and follow these steps:
 
  * Create a virtualenv and activate it
  * Clone your repository locally
@@ -55,14 +55,14 @@ is a better way to structure the code so that it is more readable.
 Documentation
 =============
 
-You can edit the documentation by editing files in ``docs/``. This project
+You can edit the documentation by editing files in :file:`docs/`. This project
 uses sphinx to turn ``ReStructuredText`` into the HTML docs you are reading.
 
 In order to build the docs in to HTML, you can run::
 
     tox -e docs
 
-This will build the docs, and place the result in ``docs/_build/html``.
+This will build the docs, and place the result in :file:`docs/_build/html`.
 Alternatively, you can run::
 
     tox -e livedocs
@@ -89,7 +89,7 @@ For example, to add Deutsch::
     cd oauth2_provider
     django-admin makemessages --locale de
 
-Then edit ``locale/de/LC_MESSAGES/django.po`` to add your translations.
+Then edit :file:`locale/de/LC_MESSAGES/django.po` to add your translations.
 
 When deploying your app, don't forget to compile the messages with::
 
@@ -108,16 +108,16 @@ And, if a new migration is needed, use::
 
     django-admin makemigrations --settings tests.mig_settings
 
-Auto migrations frequently have ugly names like `0004_auto_20200902_2022`. You can make your migration
-name "better" by adding the `-n name` option::
+Auto migrations frequently have ugly names like ``0004_auto_20200902_2022``. You can make your migration
+name "better" by adding the ``-n name`` option::
 
     django-admin makemigrations --settings tests.mig_settings -n widget
 
 
 Pull requests
 =============
 
-Please avoid providing a pull request from your `master` and use **topic branches** instead; you can add as many commits
+Please avoid providing a pull request from your ``master`` and use **topic branches** instead; you can add as many commits
 as you want but please keep them in one branch which aims to solve one single issue. Then submit your pull request. To
 create a topic branch, simply do::
 
@@ -129,7 +129,7 @@ When you're ready to submit your pull request, first push the topic branch to yo
     git push origin fix-that-issue
 
 Now you can go to your repository dashboard on GitHub and open a pull request starting from your topic branch. You can
-apply your pull request to the `master` branch of django-oauth-toolkit (this should be the default behaviour of GitHub
+apply your pull request to the ``master`` branch of django-oauth-toolkit (this should be the default behaviour of GitHub
 user interface).
 
 When you begin your PR, you'll be asked to provide the following:
@@ -150,29 +150,29 @@ When you begin your PR, you'll be asked to provide the following:
 
 * Update the documentation (in `docs/`) to describe the new or changed functionality.
 
-* Update `CHANGELOG.md` (only for user relevant changes). We use `Keep A Changelog <https://keepachangelog.com/en/1.0.0/>`_
+* Update ``CHANGELOG.md`` (only for user relevant changes). We use `Keep A Changelog <https://keepachangelog.com/en/1.0.0/>`_
   format which categorizes the changes as:
 
-  * `Added` for new features.
+  * ``Added`` for new features.
 
-  * `Changed` for changes in existing functionality.
+  * ``Changed`` for changes in existing functionality.
 
-  * `Deprecated` for soon-to-be removed features.
+  * ``Deprecated`` for soon-to-be removed features.
 
-  * `Removed` for now removed features.
+  * ``Removed`` for now removed features.
 
-  * `Fixed` for any bug fixes.
+  * ``Fixed`` for any bug fixes.
 
-  * `Security` in case of vulnerabilities. (Please report any security issues to the
-     JazzBand security team `<[email protected]>`. Do not file an issue on the tracker
+  * ``Security`` in case of vulnerabilities. (Please report any security issues to the
+     JazzBand security team ``<[email protected]>``. Do not file an issue on the tracker
      or submit a PR until directed to do so.)
 
-* Make sure your name is in `AUTHORS`. We want to give credit to all contributors!
+* Make sure your name is in :file:`AUTHORS`. We want to give credit to all contributors!
 
 If your PR is not yet ready to be merged mark it as a Work-in-Progress
-By prepending `WIP:` to the PR title so that it doesn't get inadvertently approved and merged.
+By prepending ``WIP:`` to the PR title so that it doesn't get inadvertently approved and merged.
 
-Make sure to request a review by assigning Reviewer `jazzband/django-oauth-toolkit`.
+Make sure to request a review by assigning Reviewer ``jazzband/django-oauth-toolkit``.
 This will assign the review to the project team and a member will review it. In the meantime you can continue to add
 commits to your topic branch (and push them up to GitHub) either if you see something that needs changing, or in
 response to a reviewer's comments.  If a reviewer asks for changes, you do not need to close the pull and reissue it
@@ -194,7 +194,7 @@ Then merge the changes that you fetched::
 
     git merge upstream/master
 
-For more info, see http://help.github.com/fork-a-repo/
+For more information, see the `GitHub Docs on forking the repository <https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo>`_.
 
 .. note:: Please be sure to rebase your commits on the master when possible, so your commits can be fast-forwarded: we
     try to avoid *merge commits* when they are not necessary.
@@ -209,7 +209,7 @@ The Checklist
 
 A checklist template is automatically added to your PR when you create it. Make sure you've done all the
 applicable steps and check them off to indicate you have done so. This is
-what you'll see when creating your PR:
+what you'll see when creating your PR::
 
   Fixes #
 
@@ -251,7 +251,7 @@ You can check your coverage locally with the `coverage <https://pypi.org/project
   pip install coverage
   coverage html -d mycoverage
 
-Open mycoverage/index.html in your browser and you can see a coverage summary and coverage details for each file.
+Open :file:`mycoverage/index.html` in your browser and you can see a coverage summary and coverage details for each file.
 
 There's no need to wait for Codecov to complain after you submit your PR.
 
@@ -263,8 +263,9 @@ Try reading our code and grasp the overall philosophy regarding method and varia
 the sake of readability, keep in mind that *simple is better than complex*. If you feel the code is not straightforward,
 add a comment. If you think a function is not trivial, add a docstrings.
 
-To see if your code formatting will pass muster use: `tox -e flake8`
+To see if your code formatting will pass muster use::
 
+  tox -e flake8
 
 The contents of this page are heavily based on the docs from `django-admin2 <https://github.com/twoscoops/django-admin2>`_
 
@@ -301,14 +302,14 @@ and rtfd.io. This checklist is a reminder of the required steps.
   to make them meaningful to users.
 - Make a final PR for the release that updates:
 
-  - CHANGELOG to show the release date.
-  - `oauth2_provider/__init__.py` to set `__version__ = "..."`
+  - :file:`CHANGELOG.md` to show the release date.
+  - :file:`oauth2_provider/__init__.py` to set ``__version__ = "..."``
 
 - Once the final PR is merged, create and push a tag for the release. You'll shortly
   get a notification from Jazzband of the availability of two pypi packages (source tgz
   and wheel). Download these locally before releasing them.
-- Do a `tox -e build` and extract the downloaded and bullt wheel zip and tgz files into
-  temp directories and do a `diff -r` to make sure they have the same content.
+- Do a ``tox -e build`` and extract the downloaded and built wheel zip and tgz files into
+  temp directories and do a ``diff -r`` to make sure they have the same content.
   (Unfortunately the checksums do not match due to timestamps in the metadata
   so you need to compare all the files.)
 - Once happy that the above comparison checks out, approve the releases to Pypi.org.

docs/getting_started.rst

@@ -42,7 +42,7 @@ Create a Django project::
 
     django-admin startproject iam
 
-This will create a mysite directory in your current directory. With the following estructure::
+This will create a mysite directory in your current directory. With the following structure::
 
     .
     └── iam
@@ -109,7 +109,7 @@ Configure ``users.User`` to be the model used for the ``auth`` application by ad
 
 .. code-block:: python
 
-    AUTH_USER_MODEL='users.User'
+    AUTH_USER_MODEL = 'users.User'
 
 Create inital migration for ``users`` application ``User`` model::
 
@@ -203,7 +203,7 @@ Last change, add ``LOGIN_URL`` to :file:`iam/settings.py`:
 
 .. code-block:: python
 
-    LOGIN_URL='/admin/login/'
+    LOGIN_URL = '/admin/login/'
 
 We will use Django Admin login to make our life easy.
 
@@ -332,7 +332,7 @@ To be more easy to visualize::
 
 The OAuth2 provider will return the follow response:
 
-.. code-block:: javascript
+.. code-block:: json
 
     {
       "access_token": "jooqrnOrNa0BrNWlg68u9sl6SkdFZg",
@@ -402,7 +402,7 @@ To be easier to visualize::
 
 The OAuth2 provider will return the following response:
 
-.. code-block:: javascript
+.. code-block:: json
 
     {
         "access_token": "PaZDOD5UwzbGOFsQr34LQ7JUYOj3yK",

docs/install.rst

@@ -1,11 +1,11 @@
 Installation
 ============
 
-Install with pip
-::
+Install with pip::
+
     pip install django-oauth-toolkit
 
-Add `oauth2_provider` to your `INSTALLED_APPS`
+Add ``oauth2_provider`` to your ``INSTALLED_APPS``
 
 .. code-block:: python
 
@@ -15,7 +15,7 @@ Add `oauth2_provider` to your `INSTALLED_APPS`
     )
 
 
-If you need an OAuth2 provider you'll want to add the following to your urls.py
+If you need an OAuth2 provider you'll want to add the following to your :file:`urls.py`
 
 .. code-block:: python
 
@@ -26,15 +26,14 @@ If you need an OAuth2 provider you'll want to add the following to your urls.py
         path('o/', include('oauth2_provider.urls', namespace='oauth2_provider')),
     ]
 
-Or using `re_path()`
+Or using ``re_path()``
 
 .. code-block:: python
 
     from django.urls import include, re_path
 
     urlpatterns = [
         ...
-
         re_path(r'^o/', include('oauth2_provider.urls', namespace='oauth2_provider')),
     ]
 
@@ -43,7 +42,7 @@ Sync your database
 
 .. sourcecode:: sh
 
-    $ python manage.py migrate oauth2_provider
+    python manage.py migrate oauth2_provider
 
 Next step is :doc:`getting started <getting_started>` or :doc:`first tutorial <tutorial/tutorial_01>`.
 

docs/management_commands.rst

@@ -92,5 +92,5 @@ The ``createapplication`` management command provides a shortcut to create a new
       --force-color         Force colorization of the command output.
       --skip-checks         Skip system checks.
 
-If you let `createapplication` auto-generate the secret then it displays the value before hashing it.
+If you let ``createapplication`` auto-generate the secret then it displays the value before hashing it.