add extlinks + external links open in new tab

Author: rmorshea

docs/source/_exts/patched_html_translator.py

@@ -0,0 +1,24 @@
+from sphinx.util.docutils import is_html5_writer_available
+from sphinx.writers.html import HTMLTranslator
+from sphinx.writers.html5 import HTML5Translator
+
+
+class PatchedHTMLTranslator(
+    HTML5Translator if is_html5_writer_available() else HTMLTranslator
+):
+    def starttag(self, node, tagname, *args, **attrs):
+        if (
+            tagname == "a"
+            and "target" not in attrs
+            and (
+                "external" in attrs.get("class", "")
+                or "external" in attrs.get("classes", [])
+            )
+        ):
+            attrs["target"] = "_blank"
+            attrs["ref"] = "noopener noreferrer"
+        return super().starttag(node, tagname, *args, **attrs)
+
+
+def setup(app):
+    app.set_translator("html", PatchedHTMLTranslator)

docs/source/changelog.rst

@@ -17,39 +17,39 @@ with respect to its siblings in the layout. The
 :attr:`~idom.config.IDOM_FEATURE_INDEX_AS_DEFAULT_KEY` feature flag has been introduced
 to allow users to enable this behavior early.
 
-- add feature flag for default key behavior - `42ee01c <https://github.com/idom-team/idom/commit/42ee01c>`__
-- use unique object instead of index as default key - `5727ab4 <https://github.com/idom-team/idom/commit/5727ab4>`__
-- make HookCatcher/StaticEventHandlers testing utils - `1abfd76 <https://github.com/idom-team/idom/commit/1abfd76>`__
-- add element and component identity - `5548f02 <https://github.com/idom-team/idom/commit/5548f02>`__
-- minor doc updates - `e5511d9 <https://github.com/idom-team/idom/commit/e5511d9>`__
-- add tests for callback identity preservation with keys - `72e03ec <https://github.com/idom-team/idom/commit/72e03ec>`__
-- add 'key' to VDOM spec - `c3236fe <https://github.com/idom-team/idom/commit/c3236fe>`__
-- Rename validate_serialized_vdom to validate_vdom - `d04faf9 <https://github.com/idom-team/idom/commit/d04faf9>`__
-- EventHandler should not serialize itself - `f7a59f2 <https://github.com/idom-team/idom/commit/f7a59f2>`__
-- fix docs typos - `42b2e20 <https://github.com/idom-team/idom/commit/42b2e20>`__
-- fixes: #331 - add roadmap to docs - `4226c12 <https://github.com/idom-team/idom/commit/4226c12>`__
+- add feature flag for default key behavior - :commit:`42ee01c`
+- use unique object instead of index as default key - :commit:`5727ab4`
+- make HookCatcher/StaticEventHandlers testing utils - :commit:`1abfd76`
+- add element and component identity - :commit:`5548f02`
+- minor doc updates - :commit:`e5511d9`
+- add tests for callback identity preservation with keys - :commit:`72e03ec`
+- add 'key' to VDOM spec - :commit:`c3236fe`
+- Rename validate_serialized_vdom to validate_vdom - :commit:`d04faf9`
+- EventHandler should not serialize itself - :commit:`f7a59f2`
+- fix docs typos - :commit:`42b2e20`
+- fixes: #331 - add roadmap to docs - :commit:`4226c12`
 
 0.23.1
 ------
 
-- fix non-deterministic return order in install() - `494d5c2 <https://github.com/idom-team/idom/commit/494d5c2>`__
+- fix non-deterministic return order in install() - :commit:`494d5c2`
 
 0.23.0
 ------
 
-- add changelog to docs - `9cbfe94 <https://github.com/idom-team/idom/commit/9cbfe94>`__
-- automatically reconnect to server - `3477e2b <https://github.com/idom-team/idom/commit/3477e2b>`__
-- allow no reconnect in client - `ef263c2 <https://github.com/idom-team/idom/commit/ef263c2>`__
-- cleaner way to specify import sources - `ea19a07 <https://github.com/idom-team/idom/commit/ea19a07>`__
-- add the idom-react-client back into the main repo - `5dcc3bb <https://github.com/idom-team/idom/commit/5dcc3bb>`__
-- implement fastapi render server - `94e0620 <https://github.com/idom-team/idom/commit/94e0620>`__
-- improve docstring for IDOM_CLIENT_BUILD_DIR - `962d885 <https://github.com/idom-team/idom/commit/962d885>`__
-- cli improvements - `788fd86 <https://github.com/idom-team/idom/commit/788fd86>`__
-- rename SERIALIZED_VDOM_JSON_SCHEMA to VDOM_JSON_SCHEMA - `74ad578 <https://github.com/idom-team/idom/commit/74ad578>`__
-- better logging for modules - `39565b9 <https://github.com/idom-team/idom/commit/39565b9>`__
-- move client utils into private module - `f825e96 <https://github.com/idom-team/idom/commit/f825e96>`__
-- redirect BUILD_DIR imports to IDOM_CLIENT_BUILD_DIR option - `53fb23b <https://github.com/idom-team/idom/commit/53fb23b>`__
-- upgrade snowpack - `5697a2d <https://github.com/idom-team/idom/commit/5697a2d>`__
-- better logs for idom.run + flask server - `2b34e3d <https://github.com/idom-team/idom/commit/2b34e3d>`__
-- move package to src dir - `066c9c5 <https://github.com/idom-team/idom/commit/066c9c5>`__
-- idom restore uses backup - `773f78e <https://github.com/idom-team/idom/commit/773f78e>`__
+- add changelog to docs - :commit:`9cbfe94`
+- automatically reconnect to server - :commit:`3477e2b`
+- allow no reconnect in client - :commit:`ef263c2`
+- cleaner way to specify import sources - :commit:`ea19a07`
+- add the idom-react-client back into the main repo - :commit:`5dcc3bb`
+- implement fastapi render server - :commit:`94e0620`
+- improve docstring for IDOM_CLIENT_BUILD_DIR - :commit:`962d885`
+- cli improvements - :commit:`788fd86`
+- rename SERIALIZED_VDOM_JSON_SCHEMA to VDOM_JSON_SCHEMA - :commit:`74ad578`
+- better logging for modules - :commit:`39565b9`
+- move client utils into private module - :commit:`f825e96`
+- redirect BUILD_DIR imports to IDOM_CLIENT_BUILD_DIR option - :commit:`53fb23b`
+- upgrade snowpack - :commit:`5697a2d`
+- better logs for idom.run + flask server - :commit:`2b34e3d`
+- move package to src dir - :commit:`066c9c5`
+- idom restore uses backup - :commit:`773f78e`

docs/source/conf.py

@@ -27,6 +27,15 @@
 copyright = "2020, Ryan Morshead"
 author = "Ryan Morshead"
 
+# -- Common External Links ---------------------------------------------------
+
+extlinks = {
+    "issue": ("https://github.com/idom-team/idom/issues/%s", "#"),
+    "pull": ("https://github.com/idom-team/idom/pulls/%s", "#"),
+    "discussion": ("https://github.com/idom-team/idom/discussions/%s", "#"),
+    "commit": ("https://github.com/idom-team/idom/commit/%s", ""),
+}
+
 # -- General configuration ---------------------------------------------------
 
 # If your documentatirston needs a minimal Sphinx version, state it here.
@@ -42,15 +51,17 @@
     "sphinx.ext.coverage",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
+    "sphinx.ext.extlinks",
     "sphinx.ext.autosectionlabel",
     "sphinx_autodoc_typehints",
     "sphinx_panels",
     "sphinx_copybutton",
     # custom extensions
-    "interactive_widget",
-    "widget_example",
     "async_doctest",
     "copy_vdom_json_schema",
+    "interactive_widget",
+    "patched_html_translator",
+    "widget_example",
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/roadmap.rst

@@ -25,9 +25,10 @@ Roadmap
     primarilly be a tool for optimization rather than a functional requirement.
 
     Related issues:
+        :issue:`330`, :issue:`19`
 
-    - https://github.com/idom-team/idom/issues/330
-    - https://github.com/idom-team/idom/issues/19
+    Related work:
+        :pull:`345`
 
 **Reconsider Custom Component Interface**:
     One problem that's come up several times while implementing alternate client
@@ -45,6 +46,7 @@ Roadmap
     effort.
 
     Related issues:
+        :issue:`13`, :issue:`6`
 
-    - https://github.com/idom-team/idom-jupyter/issues/13
-    - https://github.com/idom-team/idom-dash/issues/6
+    Related work:
+        in progress...

noxfile.py

@@ -175,7 +175,7 @@ def parse_commit_reference(commit_ref: str) -> Tuple[str, str, str]:
 
     for sha, msg, _ in map(parse_commit_reference, commit_references):
         if rst_format:
-            sha_repr = f"`{sha} <https://github.com/idom-team/idom/commit/{sha}>`__"
+            sha_repr = f":commit:`{sha}`"
         else:
             sha_repr = sha
         print(f"- {msg} - {sha_repr}")