From 53df80b44f2bfeedf0bd43895a32f3512ad34060 Mon Sep 17 00:00:00 2001 From: James Knight Date: Sat, 29 Jun 2024 09:55:51 -0400 Subject: [PATCH] doc: cleanup configuration references With the recently supported lref role [1], updating various links to use this capability. In addition, cleanup other links/literals that can take advantage of this role. [1]: 71f6bb938de6f3c6b9a5f9015dd0b5da12882e50 Signed-off-by: James Knight --- doc/advanced-publish-permissions.rst | 3 +-- doc/configuration.rst | 5 ++++- doc/directives.rst | 27 +++++++++++++-------------- doc/guide-ci.rst | 28 +++++++++++++--------------- doc/guide-class-hints.rst | 2 +- doc/guide-math.rst | 13 ++++++------- doc/roles.rst | 8 ++++---- doc/tips.rst | 7 +++---- doc/tutorial.rst | 14 +++++++------- 9 files changed, 52 insertions(+), 55 deletions(-) diff --git a/doc/advanced-publish-permissions.rst b/doc/advanced-publish-permissions.rst index 83c47b96..19059675 100644 --- a/doc/advanced-publish-permissions.rst +++ b/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`) -capabilitity. +:lref:`confluence_cleanup_purge` capabilitity. For environments using an OAuth connector, the following scopes are required: diff --git a/doc/configuration.rst b/doc/configuration.rst index 0f18ac08..512adf39 100644 --- a/doc/configuration.rst +++ b/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 diff --git a/doc/directives.rst b/doc/directives.rst index 06edb284..e3a93eed 100644 --- a/doc/directives.rst +++ b/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`). + 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`). + 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`). + 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`). 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`). 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`) 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`). + (see :lref:`confluence_editor`). .. rst:directive:: confluence_doc diff --git a/doc/guide-ci.rst b/doc/guide-ci.rst index 6aff1380..91c539af 100644 --- a/doc/guide-ci.rst +++ b/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`) and ``confluence_api_token`` -(:ref:`ref`) 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`) 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 diff --git a/doc/guide-class-hints.rst b/doc/guide-class-hints.rst index 60ad6c21..93550618 100644 --- a/doc/guide-class-hints.rst +++ b/doc/guide-class-hints.rst @@ -33,7 +33,7 @@ For example: if __name__ == '__main__': main() -See also :ref:`confluence_code_block_theme `. +See also :lref:`confluence_code_block_theme`. ``strike`` ---------- diff --git a/doc/guide-math.rst b/doc/guide-math.rst index cf152450..d0e0d644 100644 --- a/doc/guide-math.rst +++ b/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`) 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 diff --git a/doc/roles.rst b/doc/roles.rst index 1f71b5e7..f1d5842b 100644 --- a/doc/roles.rst +++ b/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`) 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`) 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`). + (see :lref:`confluence_editor`). Support for inlined smart links can be created using the following roles. diff --git a/doc/tips.rst b/doc/tips.rst index 95b7b52f..3b00acb7 100644 --- a/doc/tips.rst +++ b/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`) or ``confluence_publish_postfix`` -(:ref:`ref`) options. +content can use the :lref:`confluence_publish_prefix` or +:lref:`confluence_publish_postfix` options. See also the :ref:`dry run capability ` and the :ref:`title overrides capability `. @@ -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`). +(see :lref:`confluence_timeout`). Connection troubleshooting -------------------------- diff --git a/doc/tutorial.rst b/doc/tutorial.rst index 3ceef70b..e6a5fd0a 100644 --- a/doc/tutorial.rst +++ b/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.