diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 0000000000..01a34f08b5 --- /dev/null +++ b/.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 diff --git a/docs/source/conf.py b/docs/source/conf.py index a5b5f9f7b0..ca84159767 100644 --- a/docs/source/conf.py +++ b/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,24 +192,19 @@ # -- 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': @@ -213,6 +212,12 @@ def run_role(self, name, options=None, content=None): 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? diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index c8e32deeec..0cbb6079ac 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -1,3 +1,5 @@ -recommonmark==0.4.0 -Sphinx==1.8.2 -sphinx-rtd-theme==0.4.2 \ No newline at end of file +# 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 \ No newline at end of file