RTD Fixes to enable publishing

.readthedocs.yaml

@@ -0,0 +1,14 @@
+version: 2
+
+build:
+  os: "ubuntu-20.04"
+  tools:
+    python: "3.6"
+
+sphinx:
+  builder: dirhtml
+  configuration: docs/source/conf.py
+
+python:
+  install:
+    - requirements: docs/source/requirements.txt

docs/source/conf.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python3
+
+
 # -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
@@ -11,27 +14,23 @@
 # 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
-
 import sphinx_rtd_theme
+import recommonmark
 from recommonmark.transform import AutoStructify
 
 sys.path.insert(0, os.path.abspath('.'))
-
-
 # -- Project information -----------------------------------------------------
 
 project = 'Indy Plenum'
-copyright = '2018, Hyperledger Indy'
+copyright = '2024, Hyperledger Indy'
 author = 'Hyperledger Indy'
 
 # The short X.Y version
-version = ''
+version = u'1.0'
 # The full version, including alpha/beta/rc tags
-release = ''
-
+release = u'1.13.1rc4'
 # for documentation module
 nickname = 'plenum'
 # -- General configuration ---------------------------------------------------
@@ -45,14 +44,21 @@
 # ones.
 extensions = [
     'sphinx.ext.intersphinx',
+    'recommonmark',
+    'sphinx.ext.autosectionlabel',
 ]
 
+# Prefix document path to section labels, otherwise autogenerated labels would look like 'heading'
+# rather than 'path/to/file:heading'
+autosectionlabel_prefix_document = True
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
+
 source_suffix = ['.rst', '.md']
 # source_suffix = '.rst'
 
@@ -64,12 +70,12 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = "en"
 
 # 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']
+exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store']
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -80,9 +86,6 @@
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
 #
-# html_theme = 'alabaster'
-
-
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
@@ -160,7 +163,8 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'IndyPlenum', 'Indy Plenum Documentation',
-     author, 'IndyPlenum', 'One line description of project.',
+     author, 'IndyPlenum', 'Plenum is the heart of the distributed ledger technology inside Hyperledger
+Indy.',
      'Miscellaneous'),
 ]
 
@@ -188,31 +192,32 @@
 # -- Options for intersphinx extension ---------------------------------------
 
 # Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
 
 
 source_parsers = {
     '.md' : 'recommonmark.parser.CommonMarkParser',
 }
-
-def setup(app):
-    app.add_config_value('recommonmark_config', {
-            'auto_toc_tree_section': 'Contents',
-            }, True)
-    app.add_transform(AutoStructify)
-
-
 # -------------- Additional fix for Markdown parsing support ---------------
 # Once Recommonmark is fixed, remove this hack.
-# Monkey patch to fix recommonmark 0.4 doc reference issues.
 from recommonmark.states import DummyStateMachine
+# Monkey patch to fix recommonmark 0.4 doc reference issues.
 orig_run_role = DummyStateMachine.run_role
 def run_role(self, name, options=None, content=None):
     if name == 'doc':
         name = 'any'
     return orig_run_role(self, name, options, content)
 DummyStateMachine.run_role = run_role
 
+def setup(app):
+    app.add_config_value('recommonmark_config', {
+            'auto_toc_tree_section': 'Contents',
+            }, True)
+    app.add_transform(AutoStructify)
+
 # ------------ Remote Documentation Builder Config -----------
 # Note: this is a hacky way of maintaining a consistent sidebar amongst all the repositories. 
 # Do you have a better way to do it?

docs/source/requirements.txt

@@ -1,3 +1,5 @@
-recommonmark==0.4.0
-Sphinx==1.8.2
-sphinx-rtd-theme==0.4.2
+# Defining the exact versions for ReadTheDocs that will make sure things don't break
+sphinx==5.3.0
+sphinx_rtd_theme==1.1.1
+readthedocs-sphinx-search==0.3.2
+recommonmark