Update app dev tutorial to include Go and Java

This change uses (linked) tabs to display code snippets and
language-specific commands for the user's desired programming language.

In order to use the sphinx-tabs extension, the version of Python used to
build the docs had to be updated. Since the `n42org/tox` Docker image
used had a very old Python version baked in, and there were no more
recent versions available, the `make docs` target now uses the official
Python image. In addition to providing a much more current Python
environment, this image natively supports arm64 in addition to amd64,
allowing docs to be built on Apple Silicon Macs.

Signed-off-by: Mark S. Lewis <[email protected]>

Makefile

@@ -345,8 +345,8 @@ spaces:
 	@scripts/check_file_name_spaces.sh
 
 .PHONY: docs
-docs:
-	@docker run --rm -v $$(pwd):/docs n42org/tox:3.4.0 sh -c 'cd /docs && tox -e docs'
+docs: # Builds the documentation in html format
+	@docker run --rm -v $$(pwd):/docs python:3.12-slim sh -c 'pip install --no-input tox && cd /docs && tox -e docs'
 
 .PHONY: ccaasbuilder-clean
 ccaasbuilder-clean/%:

docs/requirements.txt

@@ -1,38 +1,39 @@
-alabaster==0.7.16
-Babel==2.14.0
-certifi==2023.11.17
-charset-normalizer==3.3.2
+alabaster==1.0.0
+babel==2.16.0
+certifi==2024.8.30
+charset-normalizer==3.4.0
 commonmark==0.9.1
-docutils==0.20.1
-idna==3.6
+docutils==0.21.2
+idna==3.10
 imagesize==1.4.1
-importlib-metadata==6.7.0
-Jinja2==3.1.3
+importlib-metadata==8.5.0
+Jinja2==3.1.4
 markdown-it-py==3.0.0
-MarkupSafe==2.1.3
-mdit-py-plugins==0.4.0
+MarkupSafe==3.0.1
+mdit-py-plugins==0.4.2
 mdurl==0.1.2
-myst-parser==2.0.0
-packaging==23.2
-Pygments==2.17.2
-python-markdown-math==0.2
-pytz==2023.3
-PyYAML==6.0.1
+myst-parser==4.0.0
+packaging==24.1
+Pygments==2.18.0
+python-markdown-math==0.8
+pytz==2024.2
+PyYAML==6.0.2
 readthedocs-sphinx-ext==2.2.5
 recommonmark==0.7.1
-requests==2.31.0
+requests==2.32.3
 six==1.16.0
 snowballstemmer==2.2.0
-Sphinx==7.2.6
-sphinx-rtd-theme==2.0.0
-sphinxcontrib-applehelp==1.0.8
-sphinxcontrib-devhelp==1.0.6
-sphinxcontrib-htmlhelp==2.0.5
+Sphinx==8.1.3
+sphinx-rtd-theme==3.0.1
+sphinx-tabs==3.4.7
+sphinxcontrib-applehelp==2.0.0
+sphinxcontrib-devhelp==2.0.0
+sphinxcontrib-htmlhelp==2.1.0
 sphinxcontrib-jquery==4.1
 sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.7
-sphinxcontrib-serializinghtml==1.1.10
-sphinxcontrib-websupport==1.2.4
-typing_extensions==4.7.1
-urllib3==2.1.0
-zipp==3.15.0
+sphinxcontrib-qthelp==2.0.0
+sphinxcontrib-serializinghtml==2.0.0
+sphinxcontrib-websupport==2.0.0
+typing_extensions==4.12.2
+urllib3==2.2.3
+zipp==3.20.2

docs/source/conf.py

@@ -10,29 +10,30 @@
 import os
 import sys
 from os import environ
-sys.path.insert(0, os.path.abspath('.'))
+
+sys.path.insert(0, os.path.abspath("."))
 
 import sphinx_rtd_theme
 
-rtd_tag = 'latest'
-if environ.get('READTHEDOCS_VERSION') is not None:
-    rtd_tag = os.environ['READTHEDOCS_VERSION']
+rtd_tag = "latest"
+if environ.get("READTHEDOCS_VERSION") is not None:
+    rtd_tag = os.environ["READTHEDOCS_VERSION"]
 
 
 placeholder_replacements = {
     "{BRANCH}": "main",
-    "{BRANCH_DOC}" : "latest", # Used to target the correct ReadTheDocs distribution version
-    "{RTD_TAG}": rtd_tag
+    "{BRANCH_DOC}": "latest",  # Used to target the correct ReadTheDocs distribution version
+    "{RTD_TAG}": rtd_tag,
 }
 
 # -- Project information -----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
 
-project = u'Hyperledger Fabric Docs'
-copyright = u'2017-2024, Hyperledger Foundation'
-author = u'Hyperledger Foundation'
-release = u'main'
-version = u'main'
+project = "Hyperledger Fabric Docs"
+copyright = "2017-2024, Hyperledger Foundation"
+author = "Hyperledger Foundation"
+release = "main"
+version = "main"
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -46,43 +47,43 @@
 # Sphinx projects.
 # Installed version as per directive in docs/requirement.txt
 source_parsers = {
-    '.md': 'recommonmark.parser.CommonMarkParser',
+    ".md": "recommonmark.parser.CommonMarkParser",
 }
 
-# The file extensions of source files. Sphinx considers the files with this suffix as sources. 
+# The file extensions of source files. Sphinx considers the files with this suffix as sources.
 # The value can be a dictionary mapping file extensions to file types. For example:
-source_suffix = {
-    '.rst': 'restructuredtext',
-    '.md': 'markdown'
-}
+source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # Used to be "master_doc"
 # The main toctree document
-root_doc = 'index'
+root_doc = "index"
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = True
 
-extensions = ['sphinx.ext.autodoc',
-    'sphinx.ext.doctest',
-    'sphinx.ext.intersphinx',
-    'sphinx.ext.todo',
-    'sphinx.ext.imgmath',
-    'sphinx.ext.ifconfig',
-    'sphinx.ext.viewcode',
-    'myst_parser',
-    'sphinxcontrib.jquery']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.imgmath",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "myst_parser",
+    "sphinxcontrib.jquery",
+    "sphinx_tabs.tabs",
+]
 
 # -- Special API Accesses -------------------------------------------------
 # They create an instance of the Sphinx object, documented here
@@ -91,31 +92,33 @@
 #
 # We then call it to perform special/specific customizations.
 
+
 def placeholderReplace(app, docname, source):
     result = source[0]
     for key in app.config.placeholder_replacements:
         result = result.replace(key, app.config.placeholder_replacements[key])
     source[0] = result
 
+
 def setup(app):
-    app.add_css_file('css/custom.css')
-    app.add_config_value('placeholder_replacements', {}, True)
-    app.connect('source-read', placeholderReplace)
+    app.add_css_file("css/custom.css")
+    app.add_config_value("placeholder_replacements", {}, True)
+    app.connect("source-read", placeholderReplace)
 
 
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 # html_css_files = ['css/custom.css']
 
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
 
-html_static_path = ['_static']
+html_static_path = ["_static"]
 
 html_add_permalinks = True
 
 # -- MyST-specific Options -------------------------------------------------
 # https://myst-parser.readthedocs.io/en/latest/configuration.html#sphinx-config-options
-myst_all_links_external = True
+myst_all_links_external = True