doc: Add workaround for Read The Docs (#47)

RTD now wants an `index.html` file in the root. Otherwise RTD considers
the docs broken. Our docs use `contents.html` as entry point. Our RTD
configuration has page redirects in place:

- `/` -> `/contents.html`
- `/index.html` -> `/contents.html`

Add a dummy `index.rst` to make RTD happy. The page is hidden in the TOC
and just links to start of `contents.html` in the root. The trick ensures
that references in 3rd party documentations and search machine indexes
are kept happy.

Signed-off-by: Christian Heimes <cheimes@redhat.com>

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.11"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py

docs/source/conf.py

@@ -17,6 +17,14 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 # sys.path.insert(0, os.path.abspath('.'))
 
+import os, sys
+# add ../.. to module lookup path
+sys.path.insert(
+    0,
+    os.path.abspath(
+        os.path.join(os.path.dirname(__file__), "..", "..")
+    )
+)
 import pyasn1
 
 # -- General configuration ------------------------------------------------

docs/source/contents.rst

@@ -1,3 +1,4 @@
+.. _Start Content:
 
 ASN.1 library for Python
 ========================
@@ -159,3 +160,9 @@ On the other end of the readability spectrum, here is a quick and sweet write up
 If you are working with ASN.1, we'd highly recommend reading a proper
 book on the subject.
 
+
+.. hidden toctree to include `index.rst` for RTD
+.. toctree::
+   :hidden:
+
+   /index

docs/source/index.rst

@@ -0,0 +1,7 @@
+Index
+=====
+
+.. Make RTD happy. We have a redirect index.html to contents.html.
+
+:ref:`Start Content`
+