From 4d322f1633602e52efc345e778ce010900c52da8 Mon Sep 17 00:00:00 2001
From: Shengyu Zhang <i@silverrainz.me>
Date: Fri, 22 Dec 2023 00:17:39 +0800
Subject: [PATCH] Impl roles composing

---
 docs/_images/rst.png                   | Bin 0 -> 1060 bytes
 docs/conf.py                           |   5 ++
 docs/index.rst                         |  46 +++++++++++
 docs/usage.rst                         |  25 ++++++
 src/sphinxnotes/comboroles/__init__.py | 104 +++++++++++++++++++++++++
 5 files changed, 180 insertions(+)
 create mode 100644 docs/_images/rst.png
 create mode 100644 docs/usage.rst
 create mode 100644 src/sphinxnotes/comboroles/__init__.py

diff --git a/docs/_images/rst.png b/docs/_images/rst.png
new file mode 100644
index 0000000000000000000000000000000000000000..58a5e7e3a1cdbedf5a838d1dfee07dfe86c380da
GIT binary patch
literal 1060
zcmV+<1l#+GP)<h;3K|Lk000e1NJLTq00IO6001!o0{{R3pX4Lr00004XF*Lt007wp
z+_KsN00006P)t-s|Ns900033O(|!N|00DGTPE!Ct=GbNc00X>9L_t(|0iD6It{hhZ
z0MK*q4!h&<;++l)P~J*32t{Bd3Kx;zM55pm=<<XpC@A~^R(y>BQRWl;5frJ=Rrmpy
z=`x{mfy5YWX`GDbqM6+_8ym2n&vA8|QcCF^d^_4ZFN3%8G}^ngb``yY;GmR}yqQf}
zb)j<*qDAn=Zb}qKtLTN+8~KG(t1((cvr8{od)4oY6KA5m$D!W&#7nOEud2?`PelI_
zYA<P$|DkgbqP^PNY1h$Ws_49#wNoKF8oi+>(At}xM~f0YZ@rBv+Pm)x>g<JU(LwTd
zo<_G;$;YxQy0Fc9cQ?YYO`)Xo%y}tk<Dzp%=xoXmN*UauzwTbPDw%uT$Tm^(dAI5f
zbzEz#>38gCrF_Gm;D#zv`8h&JH=VgDq#G71c1?vU)^=&rv>IB}AF2==J1UD%H@{PB
zoQWzlNmcLKx<-jV!jA`ogSDuFY%ju@%1%^?7T+2D&AWG2o4>~&4y~Ut)?}y!vw+c2
zBWeY;VDVi(GUo3K@zSp)rizZNu@@O9MvEO1sd3N>*$tQeAw15Z+vG422DYWUNTXH1
z8F8NYSQySrz85AJ`66G8oYSwmG+qjQsK~LCi=(bHt4F7DHtEQnS?G0XgiRC^HTNB4
zi{_D2NqnN;wW-HBDqLcU{-q+x$)Y5CofFT^2E`MzNEWi#e-%ySEn17o-Yz>aI+`rH
zI$69ERci0i*&FrAEIBdw!d@|}Z22rf)Zhd9oyB1As$TD#-m~{rj052}42{J@&%Ek^
zfBL3BQ{Y+!e=MlI#<uv<;`V3$YEgAxS9;AyiP2TmAGG$qj_@l?m8<xvgKH6XDA84X
zf&for)hTAd>vfKjgX<AHv*h)%#a#`w)Sg90Ir;w{hmf4=kVV<7qs7kN8ObbS?L_cG
zf+1Q2I{4gPqifCHP1H_AM<K&mtj%Jh_d;^X&R%xYqDFA$g+5`7j)on<B8H^DVb%z;
zMTMLiM={YT(JWe24kAMZErP`qq1_Q6SeZSGlHeWNGAOIbB8-fyGUzWlCVQcj)Lmo@
zq;FNU+^=H;XA?RM_C^yGBqp<h%ihsCuF2LSy7bFpmh5GN0s}guMZ%z%_3iuKAAXSi
zVTkbI9mulYtn-i-qoVi7;sHhz>zduC;ZxsBep|;vfBS)!q|=%8{?h9(nGC)d%zC=X
zc-OG$hVzFt6ORVB*-UK9$ZE1lSdFqx8Mx?#$>kO{r6l*dTT1Cx#Wt@7=c#s+(7Uq1
eCWX#*^}hjpEL}K18Dwez0000<MNUMnLSTY%vj+75

literal 0
HcmV?d00001

diff --git a/docs/conf.py b/docs/conf.py
index 8d918e1..4a14953 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -112,4 +112,9 @@
 
 # DOG FOOD CONFIGURATION START
 
+comboroles_roles = {
+    'literal_emphasis_strong': ['literal', 'emphasis', 'strong'],
+    'parsed_literal': (['literal'], True),
+}
+
 # DOG FOOD CONFIGURATION END
diff --git a/docs/index.rst b/docs/index.rst
index 4533004..63ff889 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -8,6 +8,40 @@ Introduction
 
 .. ADDITIONAL CONTENT START
 
+The extension allows users to create roles composited by multiple roles.
+
+As we know, |rst| does not yet support `nested inline markups/roles`__,
+so text like ````***bold italic code***```` doesn't render as expected.
+With the extension, we can compose roles ``literal`` (code), ``emphasis``
+(italic), and ``strong`` (bold) to composite roles ``literal_emphasis_strong``,
+to achieve the same effect as nested inline roles:
+
+.. list-table::
+
+   * - ````***bold italic code***````
+     - ``***bold italic code***``
+     - ❌
+   * - ``:literal_emphasis_strong:`bold italic code```
+     - :literal_emphasis_strong:`bold italic code`
+     - ✔️
+
+.. warning::
+
+   Due to :ref:`internal-impl`, the extension can only composite simple roles
+   (such as `docutils' Standard Roles`__),
+   and may crash Sphinx when compositing complex roles,
+   so DO NOT report to Sphinx first if it crashes, report to here
+   :issue:`new` instead.
+
+.. |rst| image:: /_images/rst.png
+   :target: https://docutils.sourceforge.io/rst.html
+   :alt: reStructuredText
+   :height: 1em
+   :align: bottom
+
+__ https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
+__ https://docutils.sourceforge.io/docs/ref/rst/roles.html#standard-roles
+
 .. ADDITIONAL CONTENT END
 
 Getting Started
@@ -39,6 +73,17 @@ Then, add the extension name to ``extensions`` configuration item in your conf.p
 
 .. ADDITIONAL CONTENT START
 
+TODO: cfg
+
+.. list-table::
+
+   * - ``:literal_emphasis_strong:`Sphinx```
+     - :literal_emphasis_strong:`Sphinx`
+   * - ``:parsed_literal:`https://silverrainz.me```
+     - :parsed_literal:`https://silverrainz.me`
+
+See :doc:`usage` for more details.
+
 .. ADDITIONAL CONTENT END
 
 Contents
@@ -47,6 +92,7 @@ Contents
 .. toctree::
    :caption: Contents
 
+   usage
    changelog
 
 The Sphinx Notes Project
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..ed6fb96
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,25 @@
+=====
+Usage
+=====
+
+TODO:
+
+https://docutils.sourceforge.io/docs/ref/rst/roles.html
+
+======================= ===============
+Usage                   Role
+======================= ===============
+*emphasis*              ``emphasis``
+**strong emphasis**     ``strong``
+``inline literals``     ``literal``
+:sub:`sub` script       ``sub``
+:sup:`super` script     ``sup``
+======================= ===============
+
+Nested Parse
+============
+
+.. _internal-impl:
+
+Internal Implementation
+=======================
diff --git a/src/sphinxnotes/comboroles/__init__.py b/src/sphinxnotes/comboroles/__init__.py
new file mode 100644
index 0000000..ccfb2ee
--- /dev/null
+++ b/src/sphinxnotes/comboroles/__init__.py
@@ -0,0 +1,104 @@
+from __future__ import annotations
+from typing import TYPE_CHECKING, cast
+
+from sphinx.util.docutils import SphinxRole 
+
+# Memo:
+#
+# https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
+# https://stackoverflow.com/questions/44829580/composing-roles-in-restructuredtext
+
+from docutils.nodes import Node, Inline, TextElement, Text, system_message
+from docutils.parsers.rst import roles
+from docutils.parsers.rst import states
+
+if TYPE_CHECKING:
+    from sphinx.application import Sphinx
+    from sphinx.config import Config
+    from sphinx.util.typing import RoleFunction
+
+__version__ = '0.1.0'
+
+class CompositeRole(SphinxRole):
+    #: Roles to be composited
+    components: list[RoleFunction]
+    nested_parse: bool
+
+    def __init__(self, rolenames: list[str], nested_parse: bool):
+        self.components = []
+        for r in rolenames:
+            if r in roles._roles: # type: ignore[attr-defined]
+                self.components.append(roles._roles[r]) # type: ignore[attr-defined]
+            elif r in roles._role_registry: # type: ignore[attr-defined]
+                self.components.append(roles._role_registry[r]) # type: ignore[attr-defined]
+            else:
+                raise KeyError(f'no such role: {r}')
+        self.nested_parse = nested_parse
+
+
+    def run(self) -> tuple[list[Node], list[system_message]]:
+        nodes: list[TextElement] = []
+        reporter = self.inliner.reporter # type: ignore[attr-defined] 
+
+        # Run all RoleFunction, collect the produced nodes.
+        for comp in reversed(self.components): 
+            ns, sysmsgs = comp(self.name, self.rawtext, self.text, self.lineno, self.inliner, self.options, self.content)
+            if len(sysmsgs) != 0:
+                return [], sysmsgs # once system_message is thrown, return
+            if len(ns) != 1:
+                msg = reporter.error(f'role should returns exactly 1 nodes, but {len(ns)} found: {ns}', line=self.lineno)
+                return [], [msg]
+            if not isinstance(ns[0], (Inline, TextElement)):
+                msg = reporter.error(f'node {ns[0]} is not ({Inline}, {TextElement})', line=self.lineno)
+                return [], [msg]
+            n = cast(TextElement, ns[0])
+            if len(n.children) != 1:
+                msg = reporter.error(f'node {n} should has exactly 1 child, but {len(n.children)} found', line=self.lineno)
+                return [], [msg]
+            if not isinstance(n[0], Text):
+                msg = reporter.error(f'child of node {n} should have Text, but {type(n[0])} found', line=self.lineno)
+                return [], [msg]
+            nodes.append(n)
+
+
+        # ref: https://stackoverflow.com/questions/44829580/composing-roles-in-restructuredtext
+        if self.nested_parse:
+            memo = states.Struct(
+                document=self.inliner.document, # type: ignore[attr-defined] 
+                reporter=reporter, 
+                language=self.inliner.language) # type: ignore[attr-defined] 
+
+            n, sysmsgs = self.inliner.parse(self.text, self.lineno, memo, nodes[-1]) # type: ignore[attr-defined] 
+            if len(sysmsgs) != 0:
+                return [], sysmsgs
+            nodes[-1].replace(nodes[-1][0], n)
+
+        # Composite all nodes together.
+        for i in range(0, len(nodes) -1):
+            nodes[i].replace(nodes[i][0], nodes[i+1])
+
+        return [nodes[0]], []
+
+def _config_inited(app:Sphinx, config:Config) -> None:
+    for name, cfg in config.comboroles_roles.items():
+        if isinstance(cfg, list):
+            rolenames = cfg
+            nested_parse = False
+        else:
+            rolenames = cfg[0]
+            nested_parse = cfg[1]
+        app.add_role(name, CompositeRole(rolenames, nested_parse))
+        
+
+def setup(app:Sphinx):
+    """Sphinx extension entrypoint."""
+
+    app.connect('config-inited', _config_inited)
+
+    app.add_config_value('comboroles_roles', {}, 'env', types=dict[str, list[str] | tuple[list[str],bool]])
+
+    return {
+        "version": __version__,
+        "parallel_read_safe": True,
+        "parallel_write_safe": True,
+    }