docs: Enrich document

docs/changelog.rst

@@ -14,3 +14,10 @@ Change Log
       :date: yyyy-mm-dd
 
       Change log here.
+
+
+.. version:: 1.0.0a0
+   :date: 2023-12-22
+
+   The alpha version is out, enjoy~
+

docs/conf.py

@@ -139,8 +139,10 @@
 # DOG FOOD CONFIGURATION START
 
 comboroles_roles = {
-    'literal_emphasis_strong': ['literal', 'emphasis', 'strong'],
+    'strong_literal': ['strong', 'literal'],
+    'plain_literal': (['literal'], False),
     'parsed_literal': (['literal'], True),
+    'parsed_emphasis': (['emphasis'], True),
 }
 
 # DOG FOOD CONFIGURATION END

docs/conf.rst

@@ -0,0 +1,20 @@
+=============
+Configuration
+=============
+
+.. confval:: comboroles_roles
+   :type: dict[str, list[str] | tuple[list[str], bool]]
+   :default: {}
+
+   Every item of the confval declares the name of composite role and how they
+   are composited.
+
+   The ``str`` key of dict is the name of composite roles.
+
+   The value can be ``list[str]`` with an optional ``bool``.
+   The ``list[str]`` is a list of existing role name to be composited,
+   see :ref:`composite-roles` for more details.
+
+   The optional ``bool`` is flag of ``nested_parse``, indicates
+   whether the :ref:`nested-parse` function is enabled.
+   If no optional bool is given, ``nested_parse`` is disabled by default.

docs/index.rst

@@ -3,44 +3,27 @@
 
 .. include:: ../README.rst
 
+.. _intro:
+
 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::
+As we know, reStructuredText does not yet support `nested inline markups`__,
+so text like "bold code" or "italic link" doesn't render as expected.
+With the extension, we make nested inline markups possible by compositing roles:
 
-   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
+========================================== ====================================== ==
+````**bold code**````                      ``**bold code**``                      ❌
+``:strong_literal:`bold code```            :strong_literal:`bold code`            ✔️
+``*https://example.com*``                  *https://example.com*                  ❌
+``:parsed_emphasis:`https://example.com``` :parsed_emphasis:`https://example.com` ✔️
+========================================== ====================================== ==
 
 __ 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
 
@@ -73,17 +56,28 @@ Then, add the extension name to ``extensions`` configuration item in your conf.p
 
 .. ADDITIONAL CONTENT START
 
-TODO: cfg
+To create a "bold code" role that same as described in :ref:`intro`,
+Continue to add the following configuration, which tells the extension to
+composite roles :parsed_literal:`strong_` (markup: ``**foo**``) and
+:parsed_literal:`literal_` (markup: ````foo````) into a new role ``strong_literal``:
+
+.. code:: python
 
-.. list-table::
+   comboroles_roles = {
+       'strong_literal': ['strong', 'literal'],
+   }
 
-   * - ``:literal_emphasis_strong:`Sphinx```
-     - :literal_emphasis_strong:`Sphinx`
-   * - ``:parsed_literal:`https://silverrainz.me```
-     - :parsed_literal:`https://silverrainz.me`
+Then you can use it:
+
+=============================== ===========================
+``:strong_literal:`bold code``` :strong_literal:`bold code`
+=============================== ===========================
 
 See :doc:`usage` for more details.
 
+.. _strong: https://docutils.sourceforge.io/docs/ref/rst/roles.html#strong
+.. _literal: https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal
+
 .. ADDITIONAL CONTENT END
 
 Contents
@@ -93,6 +87,7 @@ Contents
    :caption: Contents
 
    usage
+   conf
    changelog
 
 The Sphinx Notes Project

docs/usage.rst

@@ -2,24 +2,100 @@
 Usage
 =====
 
-TODO:
+.. _composite-roles:
 
-https://docutils.sourceforge.io/docs/ref/rst/roles.html
+Composite Roles
+===============
 
-======================= ===============
-Usage                   Role
-======================= ===============
-*emphasis*              ``emphasis``
-**strong emphasis**     ``strong``
-``inline literals``     ``literal``
-:sub:`sub` script       ``sub``
-:sup:`super` script     ``sup``
-======================= ===============
+Users can create composite roles by adding an item to configuration item
+:confval:`comboroles_roles`. For example:
+
+.. code:: python
+
+   comboroles_roles = {
+       'strong_literal': ['strong', 'literal'],
+   }
+
+=============================== ===========================
+``:strong_literal:`bold code``` :strong_literal:`bold code`
+=============================== ===========================
+
+The above configuration creates a composite role ``strong_literal``,
+and consists of two existing roles :parsed_literal:`strong_` and
+:parsed_literal:`literal_`. so the `Interpreted Text`_ of ``literal``
+(in this case, it is "bold code") will be interpreted first by role ``literal``
+and then by ``strong`` (from the inside out). In pseudo reStructuredText, it looks
+like:
+
+.. code:: rst
+
+   :strong:`:literal:`bold code``
+
+That is why we said we implement `nested inline markups`_ in a sense.
+
+.. hint::
+
+   Here are some role names of commonly used markups:
+
+   ======================= ===========================
+   Usage                   Role
+   ======================= ===========================
+   *emphasis*              :parsed_literal:`emphasis_`
+   **strong emphasis**     :parsed_literal:`strong_`
+   ``inline literals``     :parsed_literal:`literal_`
+   :sub:`sub` script       :parsed_literal:`sub_`
+   :sup:`super` script     :parsed_literal:`sup_`
+   ======================= ===========================
+
+.. _Interpreted Text: https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#interpreted-text
+.. _nested inline markups: https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
+.. _emphasis: https://docutils.sourceforge.io/docs/ref/rst/roles.html#emphasis
+.. _strong: https://docutils.sourceforge.io/docs/ref/rst/roles.html#strong
+.. _literal: https://docutils.sourceforge.io/docs/ref/rst/roles.html#literal
+.. _sub: https://docutils.sourceforge.io/docs/ref/rst/roles.html#subscript
+.. _sup: https://docutils.sourceforge.io/docs/ref/rst/roles.html#superscript
+
+.. _nested-parse:
 
 Nested Parse
 ============
 
-.. _internal-impl:
+Normally, `Interpreted Text`_ will **not be parsed**, but will be passed directly to
+the role. Once the ``nested_parse`` flag of :confval:`comboroles_roles` is enabled,
+Interpreted Text of composite roles will **be parsed**, and then passed to the
+role. For example:
+
+.. code:: python
+
+   comboroles_roles = {
+       'parsed_literal': (['literal'], True),
+   }
+
+=================================== =============================
+````**bold code**````               ``**bold code**``
+``:parsed_literal:`**bold code**``` :parsed_literal:`**bold code**`
+=================================== =============================
+
+The above configuration creates a composite role `parsed_literal` with
+``nested_parse`` enabled, so the text "\*\*bold code\**" can be parsed.
+
+Further, hyperlinks, substitutions, and even roles inside interpreted text can
+be parsed too:
+
+========================================== =====================================
+``:parsed_literal:`https://example.com```` :parsed_literal:`https://example.com`
+``:parsed_literal:`|release|````           :parsed_literal:`|release|`
+``:parsed_literal:`RFC: :rfc:\`1459\````   :parsed_literal:`RFC: :rfc:\`1459\``
+========================================== =====================================
+
+.. note:: For nested roles, note that the backquote ````` needs to be escaped.
+
+Limitation
+==========
+
+.. warning::
 
-Internal Implementation
-=======================
+   Due to internal implementation, the extension can only used to composite
+   simple roles and may CRASH Sphinx when compositing complex roles.
+   DO NOT report to Sphinx first if it crashes, please report to here :issue:`new`
+   instead.