misc doc improvements

Author: rmorshea

docs/source/_exts/only_warn_on_broken_internal_refs.py

@@ -0,0 +1,50 @@
+from docutils import nodes
+from sphinx import addnodes
+from sphinx.application import Sphinx
+from sphinx.transforms.post_transforms import SphinxPostTransform
+from sphinx.util import logging
+
+
+logger = logging.getLogger(__name__)
+
+
+def is_public_internal_ref_target(target: str) -> bool:
+    return target.startswith("idom.") and not target.rsplit(".", 1)[-1].startswith("_")
+
+
+class OnlyWarnOnBrokenInternalRefs(SphinxPostTransform):
+    """
+    Warns about broken cross-reference links, but only for idom.
+    This is very similar to the sphinx option ``nitpicky=True`` (see
+    :py:class:`sphinx.transforms.post_transforms.ReferencesResolver`), but there
+    is no way to restrict that option to a specific package.
+    """
+
+    # this transform needs to happen before ReferencesResolver
+    default_priority = 5
+
+    def run(self) -> None:
+        for node in self.document.traverse(addnodes.pending_xref):
+            target = node["reftarget"]
+
+            if is_public_internal_ref_target(target):
+                # let the domain try to resolve the reference
+                found_ref = self.env.domains[node["refdomain"]].resolve_xref(
+                    self.env,
+                    node.get("refdoc", self.env.docname),
+                    self.app.builder,
+                    node["reftype"],
+                    target,
+                    node,
+                    nodes.TextElement("", ""),
+                )
+
+                # warn if resolve_xref did not return or raised
+                if not found_ref:
+                    logger.warning(
+                        f"API link {target} is broken.", location=node, type="ref"
+                    )
+
+
+def setup(app: Sphinx) -> None:
+    app.add_post_transform(OnlyWarnOnBrokenInternalRefs)

docs/source/architectural-patterns.rst

@@ -57,9 +57,9 @@ As a result, IDOM was developed to help solve these problems.
 Ecosystem Independence
 ----------------------
 
-IDOM has a flexible set of :ref:`core abstractions <Core Concepts>` that allow it to
-interface with its peers. At the time of writing Jupyter, Dash, and Bokeh (via Panel)
-are supported, while Streamlit is in the works:
+IDOM has a flexible set of :ref:`Core Abstractions` that allow it to interface with its
+peers. At the time of writing Jupyter, Dash, and Bokeh (via Panel) are supported, while
+Streamlit is in the works:
 
 - idom-jupyter_ (try it now with Binder_)
 - idom-dash_

docs/source/conf.py

@@ -65,6 +65,7 @@
     "patched_html_translator",
     "widget_example",
     "build_custom_js",
+    "only_warn_on_broken_internal_refs",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/core-concepts.rst renamed to docs/source/core-abstractions.rst

@@ -1,8 +1,5 @@
-Core Concepts
-=============
-
-This section covers core features of IDOM that are used in making interactive
-interfaces.
+Core Abstractions
+=================
 
 
 Pure Components

docs/source/index.rst

@@ -15,7 +15,7 @@ IDOM
     :hidden:
     :caption: Advanced Topics
 
-    core-concepts
+    core-abstractions
     javascript-components
     architectural-patterns
     specifications

noxfile.py

@@ -161,8 +161,17 @@ def test_docs(session: Session) -> None:
     """Verify that the docs build and that doctests pass"""
     install_requirements_file(session, "build-docs")
     install_idom_dev(session, extras="all")
-    session.run("sphinx-build", "-T", "-b", "html", "docs/source", "docs/build")
-    session.run("sphinx-build", "-T", "-b", "doctest", "docs/source", "docs/build")
+    session.run(
+        "sphinx-build",
+        "-T",  # show full tracebacks
+        "-W",  # turn warnings into errors
+        "--keep-going",  # complete the build, but still report warnings as errors
+        "-b",
+        "html",
+        "docs/source",
+        "docs/build",
+    )
+    session.run("sphinx-build", "-b", "doctest", "docs/source", "docs/build")
 
 
 @nox.session

src/idom/config.py

@@ -38,8 +38,8 @@
 """The location IDOM will use to store its client application
 
 This directory **MUST** be treated as a black box. Downstream applications **MUST NOT**
-assume anything about the structure of this directory see :mod:`idom.client.manage` for
-a set of publically available APIs for working with the client.
+assume anything about the structure of this directory see :mod:`idom.web.module` for a
+set of publically available APIs for working with the client.
 """
 
 IDOM_FEATURE_INDEX_AS_DEFAULT_KEY = _Option(

src/idom/server/prefab.py

@@ -80,9 +80,9 @@ def multiview_server(
 ) -> Tuple[MultiViewMount, Server[_App]]:
     """Set up a server where views can be dynamically added.
 
-    In other words this allows the user to work with IDOM in an imperative manner.
-    Under the hood this uses the :func:`idom.widgets.common.multiview` function to
-    add the views on the fly.
+    In other words this allows the user to work with IDOM in an imperative manner. Under
+    the hood this uses the :func:`idom.widgets.multiview` function to add the views on
+    the fly.
 
     Parameters:
         server: The server type to start up as a daemon
@@ -93,8 +93,8 @@ def multiview_server(
         app: Optionally provide a prexisting application to register to
 
     Returns:
-        The server instance and a function for adding views.
-        See :func:`idom.widgets.common.multiview` for details.
+        The server instance and a function for adding views. See
+        :func:`idom.widgets.multiview` for details.
     """
     mount, component = multiview()
 
@@ -123,9 +123,9 @@ def hotswap_server(
 ) -> Tuple[MountFunc, Server[_App]]:
     """Set up a server where views can be dynamically swapped out.
 
-    In other words this allows the user to work with IDOM in an imperative manner.
-    Under the hood this uses the :func:`idom.widgets.common.hotswap` function to
-    swap the views on the fly.
+    In other words this allows the user to work with IDOM in an imperative manner. Under
+    the hood this uses the :func:`idom.widgets.hotswap` function to swap the views on
+    the fly.
 
     Parameters:
         server: The server type to start up as a daemon
@@ -137,8 +137,8 @@ def hotswap_server(
         sync_views: Whether to update all displays with newly mounted components
 
     Returns:
-        The server instance and a function for swapping views.
-        See :func:`idom.widgets.common.hotswap` for details.
+        The server instance and a function for swapping views. See
+        :func:`idom.widgets.hotswap` for details.
     """
     mount, component = hotswap(update_on_change=sync_views)
 

src/idom/widgets.py

@@ -190,7 +190,7 @@ def World():
         Notebook where one might want multiple active views which can all be interacted
         with at the same time.
 
-        Refer to :func:`idom.server.imperative_server_mount` for a reference usage.
+        See :func:`idom.server.prefab.multiview_server` for a reference usage.
     """
     views: Dict[str, ComponentConstructor] = {}