refactor(docs): parse docstrings as markdown (#491)

We use markdown in docstrings of our generated modules. This causes
issues with sphinx autodoc parser.

- Switch to autodoc2 and myst to properly parse markdown.
- Patch invalid markdown before parsing.
- Switch to "Read the Docs" theme and normalize TOC for better presentation.
- Remove documentation on private module `couchdb_session_token_manager.py`

Closes #78

Author: eiri

.gitignore

@@ -59,6 +59,7 @@ python3/
 # resources
 resources/output.wav
 
+apidocs/
 docs/_build/
 deploy.sh
 docs/apis

requirements-dev.txt

@@ -9,7 +9,3 @@ pytest-rerunfailures==11.1.2
 # code coverage
 coverage==7.2.6
 pytest-cov==4.1.0
-
-# documentation
-recommonmark==0.7.1
-Sphinx==5.3.0

requirements-docs.txt

@@ -0,0 +1,6 @@
+# documentation
+recommonmark==0.7.1
+Sphinx==5.3.0
+sphinx-autodoc2==0.4.2
+myst-parser==1.0.0
+sphinx-rtd-theme==1.2.1

source/conf.py

@@ -18,11 +18,10 @@
 sys.path.insert(0, os.path.abspath('..'))
 print(os.path.abspath('..'))
 
-
 # -- Project information -----------------------------------------------------
 
 project = 'Cloudant Python SDK'
-copyright = 'Copyright IBM Corp. 2021'
+copyright = 'Copyright IBM Corp. 2021, 2023.'
 author = '@IBM/cloudant-sdks'
 
 # -- General configuration ---------------------------------------------------
@@ -31,7 +30,34 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
-    'sphinx.ext.autodoc'
+    'autodoc2',
+    'myst_parser',
+    'sphinx_rtd_theme',
+]
+
+myst_enable_extensions = ['colon_fence', 'fieldlist']
+
+autodoc2_packages = [
+    {
+        'path': '../ibmcloudant',
+        'exclude_files': [
+            'common.py',
+            'version.py',
+            'cloudant_base_service.py',
+            'couchdb_session_get_authenticator_patch.py',
+            'couchdb_session_token_manager.py'
+        ]
+    }
+]
+
+autodoc2_sort_names = True
+
+autodoc2_index_template = None
+
+autodoc2_hidden_objects = ['dunder', 'private', 'inherited']
+
+autodoc2_docstring_parser_regexes = [
+    (r'.*', 'myst'),
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -40,15 +66,41 @@
 # 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 = []
+exclude_patterns = ['apidocs/ibmcloudant/ibmcloudant.rst']
+
+# -- Patch generated rst -----------------------------------------------------
 
+file_path = '../ibmcloudant/cloudant_v1.py'
+print(f'[patching] file {file_path}')
+# read source file
+with open(file_path, 'r') as file:
+    lines = file.readlines()
+# patch broken markup
+codeblock = False
+for i in range(len(lines)):
+    # replace class vars to :param: for better rendering
+    if ':attr ' in lines[i]:
+        lines[i] = lines[i].replace(':attr', ':param')
+    # replace note with tip admonition
+    if '### Note' in lines[i]:
+        lines[i] = '        :::{tip}\n'
+        codeblock = True
+    if codeblock and lines[i] == '\n':
+        lines[i] = '        :::\n\n'
+        codeblock = False
+# write back
+with open(file_path, 'w') as file:
+    file.writelines(lines)
 
 # -- 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'
+html_theme = 'sphinx_rtd_theme'
+html_theme_options = {
+    'collapse_navigation': False
+}
 
 # 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,

source/index.rst

@@ -1,22 +1,29 @@
 .. Cloudant Python SDK documentation master file, created by
    sphinx-quickstart on Tue Jan  5 13:47:50 2021.
-   Copyright IBM Corporation 2021.
+   Copyright IBM Corporation 2021, 2023.
    SPDX-License-Identifier: Apache-2.0
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Cloudant Python SDK's documentation!
-===============================================
+Cloudant Python SDK's Documentation
+===================================
+
+CloudantV1 class
+----------------
+
+:class:`CloudantV1 <ibmcloudant.cloudant_v1.CloudantV1>`
+
+Modules
+-------
 
 .. toctree::
    :maxdepth: 4
-   :caption: Contents:
 
-   modules
+   cloudant_v1 <apidocs/ibmcloudant/ibmcloudant.cloudant_v1>
+   couchdb_session_authenticator <apidocs/ibmcloudant/ibmcloudant.couchdb_session_authenticator>
 
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`

tox.ini

@@ -19,7 +19,8 @@ exclude = .venv,.git,.tox,docs
 
 [testenv:docs]
 description = invoke sphinx-build to build the HTML docs
-deps = {[testenv]deps}
+deps =
+     -r{toxinidir}/requirements.txt
+     -r{toxinidir}/requirements-docs.txt
 basepython = python3.11
-commands = sphinx-apidoc -o {toxinidir}/source ibmcloudant "**/common.py" "**/version.py" "**/cloudant_base_service.py" "**/couchdb_session_get_authenticator_patch.py"
-           sphinx-build -d "{toxinidir}/docs_doctree" {toxinidir}/source "{toxinidir}/apidocs" --color -bhtml
+commands = sphinx-build {toxinidir}/source "{toxinidir}/apidocs" -bhtml