Merge pull request #1002 from sphinx-contrib/improve-doc-cfg-references

Improve styled configuration references for extension's documentation

Author: jdknight

doc/advanced-publish-permissions.rst

@@ -9,8 +9,7 @@ following permissions_ when attempting to publish to a configured space:
 - Attachments -- Add, Delete
 
 Delete permissions are only required for environments using the
-``confluence_cleanup_purge`` (:ref:`ref<confluence_cleanup_purge>`)
-capabilitity.
+:lref:`confluence_cleanup_purge` capabilitity.
 
 For environments using an OAuth connector, the following scopes are required:
 

doc/conf.py

@@ -2,7 +2,9 @@
 # Copyright Sphinx Confluence Builder Contributors (AUTHORS)
 
 from docutils import nodes
+from sphinx.domains.std import StandardDomain
 from sphinx.ext.autodoc import cut_lines
+from sphinx.roles import XRefRole
 from sphinx.transforms.post_transforms import SphinxPostTransform
 import sphinxcontrib.confluencebuilder
 
@@ -125,6 +127,46 @@ def run(self, **kwargs):
                 classes.append('literal-link')
 
 
+class LiteralReferenceRole(XRefRole):
+    def __init__(self):
+        super().__init__(
+            # mimic options for standard domain's xref
+            lowercase=True, innernodeclass=nodes.inline, warn_dangling=True)
+
+    def result_nodes(self, document, env, node, is_ref):
+        # force custom domain so we can manipulate resolved nodes
+        node['refdomain'] = 'cb-doc-modifiers'
+
+        # force our custom reference role to be a `ref` type to resolve
+        # it as any other standard reference
+        node['reftype'] = 'ref'
+
+        # force explicit -- for some reason non-explicit references are
+        # not resolved (limitations of this hack)
+        node['refexplicit'] = True
+
+        return [node], []
+
+
+class ConfluenceBuilderModifiersDomain(StandardDomain):
+    name = 'cb-doc-modifiers'
+    label = 'confluencebuilder (modifiers)'
+
+    def resolve_xref(self,
+            env, fromdocname, builder, typ, target, node, contnode):
+        resolved = super().resolve_xref(
+            env, fromdocname, builder, typ, target, node, contnode)
+
+        if resolved:
+            # build a literal node and wrap the inner node before returning
+            # the resolved reference
+            inner_node = resolved.next_node()
+            container_node = nodes.literal('', '', inner_node)
+            resolved.replace(inner_node, container_node)
+
+        return resolved
+
+
 def setup(app):
     app.require_sphinx('6.0')
 
@@ -136,6 +178,11 @@ def setup(app):
     # remove first line description docstrings in documentation
     app.connect('autodoc-process-docstring', cut_lines(1))
 
+    # add a custom "literal reference" which allow us to create page-to-page
+    # references that are styled in literal tags
+    app.add_domain(ConfluenceBuilderModifiersDomain)
+    app.add_role('lref', LiteralReferenceRole())
+
     # custom directives/roles for documentation
     app.add_object_type('builderval', 'builderval', objname='builders',
         indextemplate='pair: %s; builder')

doc/configuration.rst

@@ -23,7 +23,7 @@ when preparing documents.
 .. versionadded:: 1.9
 
     All options provided by this extension may be set from the running
-    environment. For example, if ``confluence_publish`` is not explicitly set
+    environment. For example, if |confluence_publish|_ is not explicitly set
     inside ``conf.py`` or provided via `Sphinx's command line`_, this extension
     may check the ``CONFLUENCE_PUBLISH`` environment option as a fallback. Note
     that this only applies options provided below and will not work for other
@@ -43,6 +43,9 @@ Essential configuration
    configuration options, where there is a stronger desire to present key
    configurations in a specific order (publish, URL, space and authentication).
 
+.. |confluence_publish| replace:: ``confluence_publish``
+.. _confluence_publish:
+
 .. confval:: confluence_publish
 
     A boolean that decides whether or not to allow publishing. This option must

doc/directives.rst

@@ -187,21 +187,21 @@ Common
         :type: v1, v2
 
         Pages are publish with the editor type configured through the
-        ``confluence_editor`` option. However, users can override the editor
-        for a specific page using the ``editor`` metadata option.
+        :lref:`confluence_editor` option. However, users can override the
+        editor for a specific page using the ``editor`` metadata option.
 
         .. code-block:: rst
 
             .. confluence_metadata::
                 :editor: v2
 
-        See also ``confluence_editor`` (:ref:`ref<confluence_editor>`).
+        See also :lref:`confluence_editor`.
 
     .. rst:directive:option:: full-width: flag
         :type: boolean
 
         Pages are publish with the full-width appearance configured through the
-        ``confluence_full_width`` option. However, users can override the
+        :lref:`confluence_full_width` option. However, users can override the
         appearance for a specific page using the ``full-width`` metadata
         option.
 
@@ -210,7 +210,7 @@ Common
             .. confluence_metadata::
                 :full-width: false
 
-        See also ``confluence_full_width`` (:ref:`ref<confluence_full_width>`).
+        See also :lref:`confluence_full_width`.
 
     .. rst:directive:option:: labels: value
         :type: space separated strings
@@ -224,8 +224,7 @@ Common
             .. confluence_metadata::
                 :labels: label-a label-b
 
-        See also ``confluence_global_labels``
-        (:ref:`ref<confluence_global_labels>`).
+        See also :lref:`confluence_global_labels`.
 
 .. rst:directive:: confluence_newline
 
@@ -426,8 +425,8 @@ Confluence documents.
     .. rst:directive:option:: server: instance
         :type: string
 
-        Indicates a named Jira server provided via ``confluence_jira_servers``
-        (:ref:`ref<confluence_jira_servers>`). When set, options ``server-id``
+        Indicates a named Jira server provided via
+        :lref:`confluence_jira_servers`. When set, options ``server-id``
         and ``server-name`` cannot be set.
 
         .. code-block:: rst
@@ -480,8 +479,8 @@ Confluence documents.
     .. rst:directive:option:: server: instance
         :type: string
 
-        Indicates a named Jira server provided via ``confluence_jira_servers``
-        (:ref:`ref<confluence_jira_servers>`). When set, options ``server-id``
+        Indicates a named Jira server provided via
+        :lref:`confluence_jira_servers`. When set, options ``server-id``
         and ``server-name`` cannot be set.
 
         .. code-block:: rst
@@ -528,8 +527,8 @@ LaTeX
 
     LaTeX support requires dvipng/dvisvgm to be installed on system; however,
     if a Confluence instance supports a LaTeX macro, the
-    ``confluence_latex_macro`` (:ref:`ref<confluence_latex_macro>`) option can
-    be used instead. For more information, please read :doc:`guide-math`.
+    :lref:`confluence_latex_macro` option can be used instead. For more
+    information, please read :doc:`guide-math`.
 
 The following directive can be used to help add LaTeX content into a
 Confluence page.
@@ -573,7 +572,7 @@ Smart links
 .. note::
 
     Smart links will only render when using the v2 editor
-    (see ``confluence_editor``; :ref:`ref<confluence_editor>`).
+    (see :lref:`confluence_editor`).
 
 .. rst:directive:: confluence_doc
 

doc/guide-ci.rst

@@ -47,12 +47,10 @@ publish token:
 Before demonstrating these methods, please note which type of authentication
 is required for the target Confluence instance. For example, if
 authenticating with an API key (Confluence Cloud; see `API tokens`_), users
-will need to configure both ``confluence_server_user``
-(:ref:`ref<confluence_server_user>`) and ``confluence_api_token``
-(:ref:`ref<confluence_api_token>`) options. However, if using a personal
+will need to configure both :lref:`confluence_server_user` and
+:lref:`confluence_api_token` options. However, if using a personal
 access token (see `Using Personal Access Tokens`_), users will need to
-configure only the ``confluence_publish_token``
-(:ref:`ref<confluence_publish_token>`) option.
+configure only the :lref:`confluence_publish_token` option.
 
 Confluence environment variables
 --------------------------------
@@ -68,13 +66,13 @@ Confluence Cloud API Key
 If using a Confluence Cloud API key, ensure the following variables are
 *not set* inside ``conf.py``:
 
-- ``confluence_api_token``
-- ``confluence_publish_token``
-- ``confluence_server_pass``
+- :lref:`confluence_api_token`
+- :lref:`confluence_publish_token`
+- :lref:`confluence_server_pass`
 
-The option ``confluence_server_user`` may be set if a user will only ever be
-published with a single API token. If the environment plans to use multiple
-tokens, ensure ``confluence_server_user`` is not set as well.
+The option :lref:`confluence_server_user` may be set if a user will only ever
+be published with a single API token. If the environment plans to use multiple
+tokens, ensure :lref:`confluence_server_user` is not set as well.
 
 Next, if the CI environment supports defining custom CI variables, create a
 new entry for ``CONFLUENCE_API_TOKEN``, holding the API token value to use
@@ -108,10 +106,10 @@ Confluence Data Center PAT
 If using a PAT, ensure the following variables are *not set* inside
 ``conf.py``:
 
-- ``confluence_api_token``
-- ``confluence_publish_token``
-- ``confluence_server_pass``
-- ``confluence_server_user``
+- :lref:`confluence_api_token`
+- :lref:`confluence_publish_token`
+- :lref:`confluence_server_pass`
+- :lref:`confluence_server_user`
 
 Next, if the CI environment supports defining custom CI variables, create a
 new entry for ``CONFLUENCE_PUBLISH_TOKEN``, holding the PAT value to use

doc/guide-class-hints.rst

@@ -33,7 +33,7 @@ For example:
         if __name__ == '__main__':
             main()
 
-See also :ref:`confluence_code_block_theme <confluence_code_block_theme>`.
+See also :lref:`confluence_code_block_theme`.
 
 ``strike``
 ----------

doc/guide-math.rst

@@ -113,13 +113,12 @@ reason why the Confluence builder extension promotes the use of
 marketplace add-on which provides LaTeX macro support, math content can instead
 be injected into these macros instead.
 
-To use a LaTeX macro, the ``confluence_latex_macro``
-(:ref:`ref<confluence_latex_macro>`) configuration option can be used. This
-option accepts either the name of a macro to use or a dictionary of macro
-options to consider (the dictionary is for more complex configurations such as
-when attempting to support block-specific and inlined-specific macros). For
-example, to specify the macro to use for any LaTeX content, the following
-can be used:
+To use a LaTeX macro, the :lref:`confluence_latex_macro` configuration option
+can be used. This option accepts either the name of a macro to use or a
+dictionary of macro options to consider (the dictionary is for more complex
+configurations such as when attempting to support block-specific and
+inlined-specific macros). For example, to specify the macro to use for any
+LaTeX content, the following can be used:
 
 .. code-block:: python
 

doc/roles.rst

@@ -60,8 +60,8 @@ LaTeX
 
     LaTeX support requires dvipng/dvisvgm to be installed on system; however,
     if a Confluence instance supports a LaTeX macro, the
-    ``confluence_latex_macro`` (:ref:`ref<confluence_latex_macro>`) option can
-    be used instead. For more information, please read :doc:`guide-math`.
+    :lref:`confluence_latex_macro` option can be used instead. For more
+    information, please read :doc:`guide-math`.
 
 The following role can be used to help include LaTeX content into generated
 Confluence documents.
@@ -119,7 +119,7 @@ generated Confluence documents.
         Contact :confluence_mention:`b9aaf35e80441f415c3a3d3c53695d0e` for help.
 
     A user mapping table can also be configured using the
-    ``confluence_mentions`` (:ref:`ref<confluence_mentions>`) option.
+    :lref:`confluence_mentions` option.
 
 .. index:: Smart links; Roles
 .. _smart-link-roles:
@@ -130,7 +130,7 @@ Smart links
 .. note::
 
     Smart links will only render when using the v2 editor
-    (see ``confluence_editor``; :ref:`ref<confluence_editor>`).
+    (see :lref:`confluence_editor`).
 
 Support for inlined smart links can be created using the following roles.
 

doc/tips.rst

@@ -63,9 +63,8 @@ is moved as a child of the container page:
 - See Also
 
 Users needing to restrict the extension from possibly mangling manually prepared
-content can use the ``confluence_publish_prefix``
-(:ref:`ref<confluence_publish_prefix>`) or ``confluence_publish_postfix``
-(:ref:`ref<confluence_publish_postfix>`) options.
+content can use the :lref:`confluence_publish_prefix` or
+:lref:`confluence_publish_postfix` options.
 
 See also the :ref:`dry run capability <confluence_publish_dryrun>` and the
 :ref:`title overrides capability <confluence_title_overrides>`.
@@ -75,7 +74,7 @@ Setting a publishing timeout
 
 By default, this extension does not define any timeouts for a publish event. It
 is recommended to provide a timeout value based on the environment being used
-(see ``confluence_timeout``; :ref:`ref<confluence_timeout>`).
+(see :lref:`confluence_timeout`).
 
 Connection troubleshooting
 --------------------------

doc/tutorial.rst

@@ -97,7 +97,7 @@ targeted.
 
 .. note::
 
-    The configuration of the space key (``confluence_space_key``) is
+    The configuration of the space key (:lref:`confluence_space_key`) is
     case-sensitive. Ensure the value matches the case found on the Confluence
     instances (typically, uppercase).
 
@@ -107,8 +107,8 @@ Recommended configurations
 By default, this extension will publish any documents to the root of a
 configured space. It can be common for most users to want to publish a
 documentation set as children of an already existing page. To take advantage of
-this feature, a user will want to define a ``confluence_parent_page`` option in
-their configuration file. For example:
+this feature, a user will want to define a :lref:`confluence_parent_page`
+option in their configuration file. For example:
 
 .. code-block:: python
 
@@ -119,8 +119,8 @@ extension to publish all documents under the ``MyDocumentation`` page.
 
 For first time users, they may wish to sanity check what content will be
 published before publishing for the first time to a Confluence instance. A user
-can perform a dryrun by configuring the ``confluence_publish_dryrun`` option in
-the project's configuration file. For example:
+can perform a dryrun by configuring the :lref:`confluence_publish_dryrun`
+option in the project's configuration file. For example:
 
 .. code-block:: python
 
@@ -146,8 +146,8 @@ building/publishing:
 
 Documentation of the project should now be published to the Confluence site.
 
-For users who set the dryrun option above (``confluence_publish_dryrun``), they
-may inspect the output of the run to confirm what the publish event will
+For users who set the dryrun option above (:lref:`confluence_publish_dryrun`),
+they may inspect the output of the run to confirm what the publish event will
 perform. If the desired result is observed, a user can remove the dryrun option
 and re-invoke the build/publish command to publish onto the configured
 Confluence instance.