Fix docs for multiple packages

.gitignore

@@ -14,7 +14,7 @@ htmlcov/
 
 # Built artifacts
 dist/
-docs/_build/
+**/docs/**/_build/
 
 # mypy
 .mypy_cache/

packages/ni.grpcdevice.v1.proto/docs/conf.py

@@ -10,6 +10,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "autoapi.extension",
     "m2r2",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -44,18 +45,16 @@
 # tell autoapi to doc the public options
 autoapi_options = list(autoapi.extension._DEFAULT_OPTIONS)
 autoapi_options.remove("private-members")  # note: remove this to include "_" members in docs
-# Restore this to start building docs for source again
-# AB#3233030
-# autoapi_dirs = [root_path / "src" / "ni"]
+autoapi_dirs = [
+    root_path / "src" / "session_pb2",
+    root_path / "src" / "session_pb2_grpc",
+]
 autoapi_python_use_implicit_namespaces = True
 autoapi_template_dir = "templates/autoapi"
 autoapi_python_class_content = "both"
 autoapi_type = "python"
 autodoc_typehints = "description"
 autoapi_file_patterns = ["*.pyi", "*.py"]
-autoapi_ignore = [
-    '**/__init__.py',
-]
 
 
 def process_docstring(app, what, name, obj, options, lines):
@@ -66,7 +65,7 @@ def process_docstring(app, what, name, obj, options, lines):
 
 def setup(sphinx):
     """Sphinx setup callback."""
-    # sphinx.connect("autodoc-process-docstring", process_docstring)
+    sphinx.connect("autodoc-process-docstring", process_docstring)
 
 
 # List of patterns, relative to source directory, that match files and
@@ -76,6 +75,7 @@ def setup(sphinx):
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
 }
 
 

packages/ni.grpcdevice.v1.proto/docs/index.rst

@@ -2,7 +2,20 @@
 Protobuf Types for NI grpc-device V1 gRPC APIs
 ##############################################
 
+.. include:: intro.inc
+
+Table of Contents
+=================
+
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+   :maxdepth: 4
+
+   autoapi/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 

packages/ni.measurementlink.discovery.v1.client/docs/conf.py

@@ -10,6 +10,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "autoapi.extension",
     "m2r2",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -51,14 +52,16 @@
 autoapi_type = "python"
 autodoc_typehints = "description"
 autoapi_file_patterns = ["*.py"]
-autoapi_ignore = [
-    '**/__init__.py',
-]
 
 
+def process_docstring(app, what, name, obj, options, lines):
+    """Make edits to docstrings as necessary"""
+    if r"@generated by mypy-protobuf" in lines[0]:
+        lines.clear()
+
 def setup(sphinx):
     """Sphinx setup callback."""
-    pass
+    sphinx.connect("autodoc-process-docstring", process_docstring)
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

packages/ni.measurementlink.discovery.v1.client/docs/index.rst

@@ -2,7 +2,20 @@
 gRPC Client for NI Discovery Service
 ####################################
 
+.. include:: intro.inc
+
+Table of Contents
+=================
+
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+   :maxdepth: 4
+
+   autoapi/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
 

packages/ni.measurementlink.discovery.v1.client/docs/templates/autoapi/index.rst

@@ -0,0 +1,19 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+..
+   Custom index: reference https://github.com/readthedocs/sphinx-autoapi/issues/298
+   Add the top most levels in "ni.measurementlink.discovery.v1.client" to the index file
+   This is needed because we don't have __init__.py file in ni
+   and ni/measurementlink etc. package as we use nested implicit namespace packages.
+
+.. toctree::
+   :titlesonly:
+
+   {% for page in pages | sort %}
+   {% if (page.top_level_object or page.name.split('.') | length == 5) and page.display %}
+   {{ page.include_path }}
+   {% endif %}
+   {% endfor %}

packages/ni.measurementlink.discovery.v1.client/src/ni/measurementlink/discovery/v1/client/_client.py

@@ -7,7 +7,8 @@
 from collections.abc import Sequence
 
 import grpc
-from ni.measurementlink.discovery.v1 import discovery_service_pb2, discovery_service_pb2_grpc
+import ni.measurementlink.discovery.v1.discovery_service_pb2 as discovery_service_pb2
+import ni.measurementlink.discovery.v1.discovery_service_pb2_grpc as discovery_service_pb2_grpc
 from ni_grpc_extensions.channelpool import GrpcChannelPool  # type: ignore[import-untyped]
 
 from ni.measurementlink.discovery.v1.client._support import (

packages/ni.measurementlink.discovery.v1.client/src/ni/measurementlink/discovery/v1/client/_support.py

@@ -12,9 +12,8 @@
 import typing
 from typing import Any
 
-from ni.measurementlink.discovery.v1 import (
-    discovery_service_pb2,
-)
+import ni.measurementlink.discovery.v1.discovery_service_pb2 as discovery_service_pb2
+
 
 if sys.platform == "win32":
     import msvcrt

packages/ni.measurementlink.discovery.v1.client/src/ni/measurementlink/discovery/v1/client/_types.py

@@ -5,9 +5,7 @@
 import typing
 from typing import NamedTuple
 
-from ni.measurementlink.discovery.v1 import (
-    discovery_service_pb2,
-)
+import ni.measurementlink.discovery.v1.discovery_service_pb2 as discovery_service_pb2
 
 
 class ServiceInfo(NamedTuple):

packages/ni.measurementlink.discovery.v1.proto/docs/conf.py

@@ -10,6 +10,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "autoapi.extension",
     "m2r2",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -44,18 +45,13 @@
 # tell autoapi to doc the public options
 autoapi_options = list(autoapi.extension._DEFAULT_OPTIONS)
 autoapi_options.remove("private-members")  # note: remove this to include "_" members in docs
-# Restore this to start building docs for source again
-# AB#3233030
-# autoapi_dirs = [root_path / "src" / "ni"]
+autoapi_dirs = [root_path / "src" / "ni"]
 autoapi_python_use_implicit_namespaces = True
 autoapi_template_dir = "templates/autoapi"
 autoapi_python_class_content = "both"
 autoapi_type = "python"
 autodoc_typehints = "description"
 autoapi_file_patterns = ["*.pyi", "*.py"]
-autoapi_ignore = [
-    '**/__init__.py',
-]
 
 
 def process_docstring(app, what, name, obj, options, lines):
@@ -66,15 +62,17 @@ def process_docstring(app, what, name, obj, options, lines):
 
 def setup(sphinx):
     """Sphinx setup callback."""
-    pass
+    sphinx.connect("autodoc-process-docstring", process_docstring)
 
 # 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", "__init__.py"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
+    "grpc": ("https://grpc.github.io/grpc/python/", None),
 }
 
 # -- Options for HTML output ----------------------------------------------

packages/ni.measurementlink.discovery.v1.proto/docs/index.rst

@@ -2,7 +2,19 @@
 Protobuf Types for NI Discovery gRPC APIs
 #########################################
 
+.. include:: intro.inc
+
+Table of Contents
+=================
+
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+   :maxdepth: 4
+
+   autoapi/index
+
+Indices and tables
+==================
 
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

packages/ni.measurementlink.discovery.v1.proto/docs/namespace.rst

@@ -0,0 +1,19 @@
+ni.measurementlink.discovery.v1
+===============================
+
+.. py:module:: ni.measurementlink.discovery.v1
+
+.. autoapi-nested-parse::
+
+   Package for ni.measurementlink.discovery.v1.
+
+
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   /autoapi/ni/measurementlink/discovery/v1/discovery_service_pb2/index
+   /autoapi/ni/measurementlink/discovery/v1/discovery_service_pb2_grpc/index

packages/ni.measurementlink.discovery.v1.proto/docs/templates/autoapi/index.rst

@@ -0,0 +1,13 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+..
+   Custom index: reference https://github.com/readthedocs/sphinx-autoapi/issues/298
+   Add the deepest implicit namespace package to the toctree.
+
+.. toctree::
+   :titlesonly:
+
+   /namespace

packages/ni.measurementlink.measurement.v1.proto/docs/conf.py

@@ -10,6 +10,7 @@
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
 extensions = [
+    "autoapi.extension",
     "m2r2",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
@@ -44,18 +45,13 @@
 # tell autoapi to doc the public options
 autoapi_options = list(autoapi.extension._DEFAULT_OPTIONS)
 autoapi_options.remove("private-members")  # note: remove this to include "_" members in docs
-# Restore this to start building docs for source again
-# AB#3233030
-# autoapi_dirs = [root_path / "src" / "ni"]
+autoapi_dirs = [root_path / "src" / "ni"]
 autoapi_python_use_implicit_namespaces = True
 autoapi_template_dir = "templates/autoapi"
 autoapi_python_class_content = "both"
 autoapi_type = "python"
 autodoc_typehints = "description"
 autoapi_file_patterns = ["*.pyi", "*.py"]
-autoapi_ignore = [
-    '**/__init__.py',
-]
 
 
 def process_docstring(app, what, name, obj, options, lines):
@@ -66,16 +62,18 @@ def process_docstring(app, what, name, obj, options, lines):
 
 def setup(sphinx):
     """Sphinx setup callback."""
-    # sphinx.connect("autodoc-process-docstring", process_docstring)
+    sphinx.connect("autodoc-process-docstring", process_docstring)
 
 
 # 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", "__init__.py"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 intersphinx_mapping = {
     "python": ("https://docs.python.org/3", None),
+    "protobuf": ("https://googleapis.dev/python/protobuf/latest/", None),
+    "grpc": ("https://grpc.github.io/grpc/python/", None),
 }
 
 

packages/ni.measurementlink.measurement.v1.proto/docs/index.rst

@@ -2,7 +2,19 @@
 Protobuf Types for NI Measurement V1 gRPC APIs
 ##############################################
 
+.. include:: intro.inc
+
+Table of Contents
+=================
+
 .. toctree::
-   :maxdepth: 1
-   :caption: Contents:
+   :maxdepth: 4
+
+   autoapi/index
+
+Indices and tables
+==================
 
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

packages/ni.measurementlink.measurement.v1.proto/docs/namespace.rst

@@ -0,0 +1,19 @@
+ni.measurementlink.measurement.v1
+=================================
+
+.. py:module:: ni.measurementlink.measurement.v1
+
+.. autoapi-nested-parse::
+
+   Package for ni.measurementlink.measurement.v1.
+
+
+
+Submodules
+----------
+
+.. toctree::
+   :maxdepth: 1
+
+   /autoapi/ni/measurementlink/measurement/v1/measurement_service_pb2/index
+   /autoapi/ni/measurementlink/measurement/v1/measurement_service_pb2_grpc/index

packages/ni.measurementlink.measurement.v1.proto/docs/templates/autoapi/index.rst

@@ -0,0 +1,13 @@
+API Reference
+=============
+
+This page contains auto-generated API reference documentation.
+
+..
+   Custom index: reference https://github.com/readthedocs/sphinx-autoapi/issues/298
+   Add the deepest implicit namespace package to the toctree.
+
+.. toctree::
+   :titlesonly:
+
+   /namespace