docs: Remove docs extra, upgrade Sphinx, enable hyperlinks to gRPC/Python/NumPy docs (#710)

* Reformat pyproject.toml

* docs: Convert docs extra to a dependency group and upgrade to latest Sphinx

* Update poetry.lock

* docs: Generate docs with Python 3.11 and install with Poetry

* docs: Update copyright year to 2017-%Y

* docs: Enable intersphinx

* pyproject.toml: Remove sphinx-click

* Update poetry.lock

* CHANGELOG.md: Document removal of `docs` extra

* docs: Add gRPC intersphinx links

* docs: Add protobuf hyperlinks

Author: bkeryan

.github/workflows/generate_docs.yml

@@ -15,7 +15,7 @@ jobs:
         uses: actions/setup-python@v5
         id: setup-python
         with:
-          python-version: "3.9"
+          python-version: "3.11"
       - name: Set up Poetry
         uses: Gr1N/setup-poetry@v9
         with:

.readthedocs.yml

@@ -3,16 +3,14 @@
 version: 2
 
 build:
-  os: ubuntu-22.04
+  os: ubuntu-24.04
   tools:
-    python: "3.9"
+    python: "3.11"
+  jobs:
+    post_create_environment:
+      - pip install poetry==1.8.2
+    post_install:
+      - VIRTUAL_ENV=$READTHEDOCS_VIRTUALENV_PATH poetry install --only main,docs
 
 sphinx:
   configuration: docs/conf.py
-
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - docs

CHANGELOG.md

@@ -31,7 +31,7 @@ All notable changes to this project will be documented in this file.
     * ...
 
 * ### Major Changes
-    * ...
+    * Removed the `docs` extra and converted it to a Poetry dependency group.
 
 * ### Known Issues
     * ...

docs/conf.py

@@ -1,24 +1,27 @@
 """Sphinx Configuration File."""
 
-import datetime
 import os
 import pathlib
 import sys
+
 import toml
 
-sys.path.insert(0, os.path.abspath('../'))
+sys.path.insert(0, os.path.abspath("../"))
 
 
 # -- General configuration ------------------------------------------------
 
-extensions = ['sphinx.ext.autodoc',
-              'sphinx.ext.coverage',
-              'sphinx.ext.viewcode',
-              'sphinx.ext.napoleon']
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.coverage",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.viewcode",
+]
 
-source_suffix = '.rst'
+source_suffix = ".rst"
 
-master_doc = 'index'
+master_doc = "index"
 
 root_path = pathlib.Path(__file__).parent.parent
 pyproj_file = root_path / "pyproject.toml"
@@ -27,57 +30,70 @@
 project = proj_config["tool"]["poetry"]["name"]
 company = "National Instruments"
 author = company
-copyright = f"{datetime.datetime.now().year}, {company}"
+copyright = f"2017-%Y, {company}"
 
 # Release is the full version, version is only the major component
 release = proj_config["tool"]["poetry"]["version"]
 version = ".".join(release.split(".")[:2])
 description = proj_config["tool"]["poetry"]["description"]
 
-language = 'en'
+language = "en"
 
-exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
-pygments_style = 'sphinx'
+pygments_style = "sphinx"
 
 todo_include_todos = False
 
+intersphinx_mapping = {
+    "grpc": ("https://grpc.github.io/grpc/python/", None),
+    "numpy": ("https://numpy.org/doc/stable/", None),
+    "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
+    "python": ("https://docs.python.org/3", None),
+}
 
 # -- Options for HTML output ----------------------------------------------
 
-html_theme = 'sphinx_rtd_theme'
+html_theme = "sphinx_rtd_theme"
 
 html_static_path = []
 
 
 # -- Options for HTMLHelp output ------------------------------------------
 
-htmlhelp_basename = 'NI-DAQmxPythonAPIdoc'
+htmlhelp_basename = "NI-DAQmxPythonAPIdoc"
 
 
 # -- Options for LaTeX output ---------------------------------------------
 
-latex_elements = {
-}
+latex_elements = {}
 
 latex_documents = [
-    (master_doc, 'NI-DAQmxPythonAPI.tex', 'NI-DAQmx Python API Documentation',
-     'National Instruments', 'manual'),
+    (
+        master_doc,
+        "NI-DAQmxPythonAPI.tex",
+        "NI-DAQmx Python API Documentation",
+        "National Instruments",
+        "manual",
+    ),
 ]
 
 
 # -- Options for manual page output ---------------------------------------
 
-man_pages = [
-    (master_doc, 'ni-daqmxpythonapi', 'NI-DAQmx Python API Documentation',
-     [author], 1)
-]
+man_pages = [(master_doc, "ni-daqmxpythonapi", "NI-DAQmx Python API Documentation", [author], 1)]
 
 
 # -- Options for Texinfo output -------------------------------------------
 
 texinfo_documents = [
-    (master_doc, 'NI-DAQmxPythonAPI', 'NI-DAQmx Python API Documentation',
-     author, 'NI-DAQmxPythonAPI', 'One line description of project.',
-     'Miscellaneous'),
+    (
+        master_doc,
+        "NI-DAQmxPythonAPI",
+        "NI-DAQmx Python API Documentation",
+        author,
+        "NI-DAQmxPythonAPI",
+        "One line description of project.",
+        "Miscellaneous",
+    ),
 ]