feat(docs): restructure in proper Sphinx project

While increasing the comprehensibility of our docs, this should also make the problem reported in readthedocs/sphinx_rtd_theme#834 go away.
desec-io · Dec 8, 2019 · 493de40 · 493de40
1 parent bb3d3e0
commit 493de40
Show file tree

Hide file tree

Showing 21 changed files with 548 additions and 424 deletions.
diff --git a/docs/.gitignore b/docs/.gitignore
@@ -1 +1 @@
-*.html
+_build/*
diff --git a/docs/Makefile b/docs/Makefile
@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/_static/.keep b/docs/_static/.keep
diff --git a/docs/_templates/.keep b/docs/_templates/.keep
diff --git a/docs/authentication.rst → docs/auth/account.rst b/docs/authentication.rst → docs/auth/account.rst
@@ -1,5 +1,4 @@
-User Registration and Management
---------------------------------
+.. _manage-account:
 
 Manage Account
 ~~~~~~~~~~~~~~
@@ -8,6 +7,9 @@ Access to the domain management API is granted to registered and logged in
 users only. Users can register an account free of charge through the API as
 described below.
 
+
+.. _obtain-a-captcha:
+
 Obtain a Captcha
 ````````````````
 
@@ -30,6 +32,8 @@ a registration request. This means that if you send an incorrect solution,
 you will have to obtain a fresh captcha and try again.
 
 
+.. _register-account:
+
 Register Account
 ````````````````
 
@@ -118,6 +122,8 @@ be created (for example, because the domain name is unavailable), your account
 will be deleted, and you can start over with a fresh registration.
 
 
+.. _log-in:
+
 Log In
 ``````
 
@@ -262,7 +268,7 @@ Delete Account
 ``````````````
 
 Before you can delete your account, it is required to first delete all your
-domains from deSEC (see `Deleting a Domain`_).
+domains from deSEC (see :ref:`deleting-a-domain`).
 
 To delete your (empty) account, send a ``POST`` request with your email
 address and password to the ``/auth/account/delete/`` endpoint::
@@ -284,6 +290,8 @@ If your account still contains domains, the server will respond with ``409
 Conflict`` and not delete your account.
 
 
+.. _log-out:
+
 Log Out
 ```````
 
@@ -293,7 +301,7 @@ the log out endpoint::
     curl -X POST https://desec.io/api/v1/auth/logout/ \
         --header "Authorization: Token i-T3b1h_OI-H9ab8tRS98stGtURe"
 
-To delete other tokens based on their ID, see `Delete Tokens`_.
+To delete other tokens based on their ID, see :ref:`delete-tokens`.
 
 
 Security Considerations
@@ -367,109 +375,3 @@ Email verification
 Password Security
     Password information is stored using `Django's default method, PBKDF2
     <https://docs.djangoproject.com/en/2.1/topics/auth/passwords/>`_.
-
-
-Manage Tokens
-~~~~~~~~~~~~~
-
-To make authentication more flexible, the API can provide you with multiple
-authentication tokens. To that end, we provide a set of token management
-endpoints that are separate from the above-mentioned log in and log out
-endpoints. The most notable difference is that the log in endpoint needs
-authentication with email address and password, whereas the token management
-endpoint is authenticated using already issued tokens.
-
-
-Retrieving All Current Tokens
-`````````````````````````````
-
-To retrieve a list of currently valid tokens, issue a ``GET`` request::
-
-    curl -X GET https://desec.io/api/v1/auth/tokens/ \
-        --header "Authorization: Token mu4W4MHuSc0HyrGD1h/dnKuZBond"
-
-The server will respond with a list of token objects, each containing a
-timestamp when the token was created (note the ``Z`` indicating the UTC
-timezone) and a UUID to identify that token. Furthermore, each token can
-carry a name that is of no operational relevance to the API (it is meant
-for user reference only). Certain API operations (such as login) will
-automatically populate the ``name`` field with values such as "login" or
-"dyndns".
-
-::
-
-    [
-        {
-            "created": "2018-09-06T07:05:54.080564Z",
-            "id": "3159e485-5499-46c0-ae2b-aeb84d627a8e",
-            "name": "login"
-        },
-        {
-            "created": "2018-09-06T08:53:26.428396Z",
-            "id": "76d6e39d-65bc-4ab2-a1b7-6e94eee0a534",
-            "name": ""
-        }
-    ]
-
-You can also retrieve an individual token by appending ``:id/`` to the URL,
-for example in order to look up a token's name or creation timestamp.
-
-
-Create Additional Tokens
-````````````````````````
-
-To create another token using the token management interface, issue a
-``POST`` request to the same endpoint::
-
-    curl -X POST https://desec.io/api/v1/auth/tokens/ \
-        --header "Authorization: Token mu4W4MHuSc0HyrGD1h/dnKuZBond" \
-        --header "Content-Type: application/json" --data @- <<< \
-        '{"name": "my new token"}'
-
-Note that the name is optional and will be empty if not specified. The server
-will reply with ``201 Created`` and the created token in the response body::
-
-    {
-        "created": "2018-09-06T09:08:43.762697Z",
-        "id": "3a6b94b5-d20e-40bd-a7cc-521f5c79fab3",
-        "token": "4pnk7u+NHvrEkFzrhFDRTjGFyX+S",
-        "name": "my new token"
-    }
-
-
-Delete Tokens
-`````````````
-
-To delete an existing token by its ID via the token management endpoints, issue a
-``DELETE`` request on the token's endpoint, replacing ``:id`` with the
-token ``id`` value::
-
-    curl -X DELETE https://desec.io/api/v1/auth/tokens/:id/ \
-        --header "Authorization: Token mu4W4MHuSc0HyrGD1h/dnKuZBond"
-
-The server will reply with ``204 No Content``, even if the token was not found.
-
-If you do not have the token UUID, but you do have the token value itself, you
-can use the `Log Out`_ endpoint to delete it.
-
-Note that, for now, all tokens have equal power -- every token can authorize
-any action. We are planning to implement scoped tokens in the future.
-
-
-Security Considerations
-```````````````````````
-
-This section is for information only. Token length and encoding may change in
-the future.
-
-Any token is generated from 168 bits of randomness at the server and stored in
-hashed format (PBKDF2-HMAC-SHA256). Guessing the token correctly or reversing
-the hash is hence practically impossible.
-
-The token value is represented by 28 characters using a URL-safe variant of
-base64 encoding. It comprises only the characters ``A-Z``, ``a-z``, ``0-9``, ``-``,
-and ``_``. (Base64 padding is not needed as the string length is a multiple of 4.)
-
-Old versions of the API encoded 20-byte tokens in 40 characters with hexadecimal
-representation. Such tokens will not be issued anymore, but remain valid until
-invalidated by the user.
diff --git a/docs/auth/tokens.rst b/docs/auth/tokens.rst
@@ -0,0 +1,108 @@
+.. _manage-tokens:
+
+Manage Tokens
+~~~~~~~~~~~~~
+
+To make authentication more flexible, the API can provide you with multiple
+authentication tokens. To that end, we provide a set of token management
+endpoints that are separate from the above-mentioned log in and log out
+endpoints. The most notable difference is that the log in endpoint needs
+authentication with email address and password, whereas the token management
+endpoint is authenticated using already issued tokens.
+
+
+Retrieving All Current Tokens
+`````````````````````````````
+
+To retrieve a list of currently valid tokens, issue a ``GET`` request::
+
+    curl -X GET https://desec.io/api/v1/auth/tokens/ \
+        --header "Authorization: Token mu4W4MHuSc0HyrGD1h/dnKuZBond"
+
+The server will respond with a list of token objects, each containing a
+timestamp when the token was created (note the ``Z`` indicating the UTC
+timezone) and a UUID to identify that token. Furthermore, each token can
+carry a name that is of no operational relevance to the API (it is meant
+for user reference only). Certain API operations (such as login) will
+automatically populate the ``name`` field with values such as "login" or
+"dyndns".
+
+::
+
+    [
+        {
+            "created": "2018-09-06T07:05:54.080564Z",
+            "id": "3159e485-5499-46c0-ae2b-aeb84d627a8e",
+            "name": "login"
+        },
+        {
+            "created": "2018-09-06T08:53:26.428396Z",
+            "id": "76d6e39d-65bc-4ab2-a1b7-6e94eee0a534",
+            "name": ""
+        }
+    ]
+
+You can also retrieve an individual token by appending ``:id/`` to the URL,
+for example in order to look up a token's name or creation timestamp.
+
+
+Create Additional Tokens
+````````````````````````
+
+To create another token using the token management interface, issue a
+``POST`` request to the same endpoint::
+
+    curl -X POST https://desec.io/api/v1/auth/tokens/ \
+        --header "Authorization: Token mu4W4MHuSc0HyrGD1h/dnKuZBond" \
+        --header "Content-Type: application/json" --data @- <<< \
+        '{"name": "my new token"}'
+
+Note that the name is optional and will be empty if not specified. The server
+will reply with ``201 Created`` and the created token in the response body::
+
+    {
+        "created": "2018-09-06T09:08:43.762697Z",
+        "id": "3a6b94b5-d20e-40bd-a7cc-521f5c79fab3",
+        "token": "4pnk7u+NHvrEkFzrhFDRTjGFyX+S",
+        "name": "my new token"
+    }
+
+
+.. _delete-tokens:
+
+Delete Tokens
+`````````````
+
+To delete an existing token by its ID via the token management endpoints, issue a
+``DELETE`` request on the token's endpoint, replacing ``:id`` with the
+token ``id`` value::
+
+    curl -X DELETE https://desec.io/api/v1/auth/tokens/:id/ \
+        --header "Authorization: Token mu4W4MHuSc0HyrGD1h/dnKuZBond"
+
+The server will reply with ``204 No Content``, even if the token was not found.
+
+If you do not have the token UUID, but you do have the token value itself, you
+can use the :ref:`log-out` endpoint to delete it.
+
+Note that, for now, all tokens have equal power -- every token can authorize
+any action. We are planning to implement scoped tokens in the future.
+
+
+Security Considerations
+```````````````````````
+
+This section is for information only. Token length and encoding may change in
+the future.
+
+Any token is generated from 168 bits of randomness at the server and stored in
+hashed format (PBKDF2-HMAC-SHA256). Guessing the token correctly or reversing
+the hash is hence practically impossible.
+
+The token value is represented by 28 characters using a URL-safe variant of
+base64 encoding. It comprises only the characters ``A-Z``, ``a-z``, ``0-9``, ``-``,
+and ``_``. (Base64 padding is not needed as the string length is a multiple of 4.)
+
+Old versions of the API encoded 20-byte tokens in 40 characters with hexadecimal
+representation. Such tokens will not be issued anymore, but remain valid until
+invalidated by the user.
diff --git a/docs/compile.sh b/docs/compile.sh
diff --git a/docs/conf.py b/docs/conf.py
@@ -0,0 +1,55 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+
+# -- Project information -----------------------------------------------------
+
+project = 'deSEC DNS API'
+copyright = '2019, deSEC e.V., Individual Contributors'
+author = 'deSEC e.V., Individual Contributors'
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ['_templates']
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = 'alabaster'
+
+# 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']
+
+master_doc = 'index'
+