Merge pull request #165 from swcurran/rtd-fixes

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: conf.py
+
+python:
+  install:
+    - requirements: requirements.txt

conf.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python3
+
+
 # -*- coding: utf-8 -*-
 #
 # Configuration file for the Sphinx documentation builder.
@@ -11,17 +14,17 @@
 # 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 = 'Hyperledger Indy HIPE'
-copyright = '2018, Hyperledger Indy'
+copyright = '2024, Hyperledger Indy'
 author = 'Hyperledger Indy'
 
 # The short X.Y version
@@ -41,17 +44,23 @@
 # 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'
+
 source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The master toctree document.
 master_doc = 'text/index'
@@ -61,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
@@ -79,6 +88,7 @@
 #
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.
@@ -153,7 +163,7 @@
 #  dir menu entry, description, category)
 texinfo_documents = [
     (master_doc, 'IndyProjectEnhancements', 'Indy Project Enhancements Documentation',
-     author, 'IndyProjectEnhancements', 'One line description of project.',
+     author, 'IndyProjectEnhancements', 'Hyperledger Indy Project Enhancement (HIPE) Documents.',
      'Miscellaneous'),
 ]
 
@@ -181,31 +191,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?
@@ -225,7 +236,7 @@ def run_role(self, name, options=None, content=None):
 
     except:
         e = sys.exc_info()[0]
-        print e
+        print(e)
     finally:      
         os.system("rm -rf remote_conf/ __pycache__/ remote_conf.py")
 

requirements.txt

@@ -0,0 +1,5 @@
+# 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