update external_cpp_references (#257)

- strips the global scope operator from confval's keys
- updates doc to use autoclass (obsoletes ignored nitpicky error).
   - also fixed a typo in task_lists doc

Author: 2bndy5

docs/apidoc/cpp/external_cpp_references.rst

@@ -20,39 +20,25 @@ define the :confval:`external_cpp_references` configuration option:
     ]
 
 .. literalinclude:: /conf.py
-   :language: python
-   :start-after: # BEGIN: sphinx_immaterial.apidoc.cpp.external_cpp_references extension options
-   :end-before: # END: sphinx_immaterial.apidoc.cpp.external_cpp_references extension options
+    :language: python
+    :start-after: # BEGIN: sphinx_immaterial.apidoc.cpp.external_cpp_references extension options
+    :end-before: # END: sphinx_immaterial.apidoc.cpp.external_cpp_references extension options
 
 .. rst-example::
 
-   .. cpp:function:: int ExtractValueFromJson(::nlohmann::json json_value);
+    .. cpp:function:: int ExtractValueFromJson(::nlohmann::json json_value);
 
-      Extracts a value from a JSON object.
+        Extracts a value from a JSON object.
 
 .. confval:: external_cpp_references
 
-   Specifies for each symbol name a dictionary specifying the URL, object type,
-   and description type:
+    A dictionary specifying the URL, object type, and descriptive text for each externally
+    documented symbol name.
 
-   .. code-block:: python
-
-      class ExternalCppReference(typing.TypedDict):
-          url: str
-          object_type: str
-          desc: str
-
-   The :python:`object_type` should be one of the object types defined by the C++ domain:
-
-   - :python:`"class"`
-   - :python:`"union"`
-   - :python:`"function"`
-   - :python:`"member"`
-   - :python:`"type"`
-   - :python:`"concept"`
-   - :python:`"enum"`
-   - :python:`"enumerator"`
+    .. autoclass:: sphinx_immaterial.apidoc.cpp.external_cpp_references.ExternalCppReference
+        :members:
+        :show-inheritance:
+        :exclude-members: __new__
 
 .. seealso::
-
-   - :doc:`cppreference`
+    :doc:`cppreference`

docs/conf.py

@@ -403,8 +403,6 @@
     # Python standard library types not present in object inventory.
     ("py:class", "Pattern"),
     ("py:class", "re.Pattern"),
-    # Config option type
-    ("py:class", "ExternalCppReference"),
     # Example Python types
     ("py:class", "example_mod.Foo"),
     ("py:class", "alias_ex.MyUnqualifiedType"),

docs/task_lists.rst

@@ -78,7 +78,7 @@ Config variables
     .. rst:directive:option:: class
         :type: string
 
-        A space delimited list of qualified names that get used as the HTMl element's
+        A space delimited list of qualified names that get used as the HTML element's
         ``class`` attribute.
 
         The ``class`` option is only applied to the containing ``div`` element.

sphinx_immaterial/apidoc/cpp/external_cpp_references.py

@@ -26,11 +26,26 @@ class ObjectInfo(NamedTuple):
 
 
 class ExternalCppReference(TypedDict):
+    """A class used to represent each dictionary field's value specified in
+    :confval:`external_cpp_references`."""
+
     url: str
     """URL to use as the target for references to this symbol."""
 
     object_type: str
-    """C++ object type."""
+    """C++ object type.
+    This should be one of the object types defined by the C++ domain:
+
+    .. hlist::
+        - :python:`"class"`
+        - :python:`"union"`
+        - :python:`"function"`
+        - :python:`"member"`
+        - :python:`"type"`
+        - :python:`"concept"`
+        - :python:`"enum"`
+        - :python:`"enumerator"`
+    """
 
     desc: str
     """Description text to include in the tooltip."""
@@ -124,6 +139,7 @@ def _load_from_config(app: sphinx.application.Sphinx) -> None:
     mappings = get_mappings(app)
 
     for name, value in app.config.external_cpp_references.items():
+        name = name.lstrip(":")
         mappings[name] = ObjectInfo(**value)