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

docs/source/life-cycle-hooks.rst

@@ -284,10 +284,9 @@ use_ref
 
     ref_container = use_ref(initial_value)
 
-Returns a mutable :class:`~idom.core.hooks.Ref` object that has a single
-:attr:`~idom.core.hooks.Ref.current` attribute that at first contains the
-``initial_state``. The identity of the ``Ref`` object will be preserved for the lifetime
-of the component.
+Returns a mutable :class:`~idom.utils.Ref` object that has a single
+:attr:`~idom.utils.Ref.current` attribute that at first contains the ``initial_state``.
+The identity of the ``Ref`` object will be preserved for the lifetime of the component.
 
 A ``Ref`` is most useful if you need to incur side effects since updating its
 ``.current`` attribute doesn't trigger a re-render of the component. You'll often use this

docs/source/roadmap.rst

@@ -34,7 +34,7 @@ Roadmap
     they need purpose-built
     `compiler plugins <https://github.com/idom-team/idom-react-component-cookiecutter/blob/1cc31b8690f84cb90dd861f2f47873b1d5711f74/%7B%7Bcookiecutter.repository_name%7D%7D/js/rollup.config.js>`__
     that will convert imports of React to point to the location ``react.js`` will be
-    once the component has been loaded via :class:`~idom.client.module.Module`.
+    once the component has been loaded via ``idom.client.module.Module``
 
     Ideally developers of custom components should be able to operate in isolation
     without assuming anything about the environment they are running in. This has the

noxfile.py

@@ -161,8 +161,18 @@ 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",
+        "-a",  # re-write all output files
+        "-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/core/dispatcher.py

@@ -36,6 +36,7 @@ async def dispatch_single_view(
     send: SendCoroutine,
     recv: RecvCoroutine,
 ) -> None:
+    """Run a dispatch loop for a single view instance"""
     with layout:
         async with create_task_group() as task_group:
             task_group.start_soon(_single_outgoing_loop, layout, send)
@@ -50,6 +51,7 @@ async def dispatch_single_view(
 async def create_shared_view_dispatcher(
     layout: Layout, run_forever: bool = False
 ) -> AsyncIterator[_SharedViewDispatcherFuture]:
+    """Enter a dispatch context where all subsequent view instances share the same state"""
     with layout:
         (
             dispatch_shared_view,
@@ -94,6 +96,7 @@ def dispatch_shared_view_soon(
 def ensure_shared_view_dispatcher_future(
     layout: Layout,
 ) -> Tuple[Future[None], SharedViewDispatcher]:
+    """Ensure the future of a dispatcher created by :func:`create_shared_view_dispatcher`"""
     dispatcher_future: Future[SharedViewDispatcher] = Future()
 
     async def dispatch_shared_view_forever() -> None: