From 6c2d10249e225ef0dfa15f9dbdffb2c3ed5508c3 Mon Sep 17 00:00:00 2001 From: James Knight Date: Sat, 19 Oct 2024 20:18:01 -0400 Subject: [PATCH] doc: move version hints to trailing part of paragraphs Signed-off-by: James Knight --- doc/builders.rst | 4 +- doc/configuration.rst | 326 +++++++++++++++++++++--------------------- doc/directives.rst | 51 ++++--- doc/roles.rst | 32 ++--- 4 files changed, 206 insertions(+), 207 deletions(-) diff --git a/doc/builders.rst b/doc/builders.rst index 77af8518..142cb2a7 100644 --- a/doc/builders.rst +++ b/doc/builders.rst @@ -17,8 +17,6 @@ The following outlines the Sphinx builders provided by this extension. .. builderval:: singleconfluence - .. versionadded:: 1.3 - The ``singleconfluence`` builder allows a user to process a Sphinx supported documentation set to generate a single document in a Confluence supported representation. The generated document can in turn be published to a @@ -27,3 +25,5 @@ The following outlines the Sphinx builders provided by this extension. .. code-block:: shell sphinx-build -b singleconfluence . _build/singleconfluence -E -a + + .. versionadded:: 1.3 diff --git a/doc/configuration.rst b/doc/configuration.rst index e10b248c..caae6433 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -80,8 +80,6 @@ Essential configuration .. confval:: confluence_space_key - .. versionadded:: 1.7 - .. note:: - Use the key value for the space, not the name of the space. For @@ -103,6 +101,8 @@ Essential configuration confluence_space_key = '~123456789' + .. versionadded:: 1.7 + .. _confluence_server_user: .. confval:: confluence_server_user @@ -133,8 +133,6 @@ Essential configuration .. confval:: confluence_api_token - .. versionadded:: 2.6 - .. tip:: Use this option for Confluence Cloud. @@ -162,12 +160,12 @@ Essential configuration confluence_api_token = 'YDYDD3qVvKV0FbkErSxaQ2olmy...AMGwaPe8=02381T9A' + .. versionadded:: 2.6 + .. _confluence_publish_token: .. confval:: confluence_publish_token - .. versionadded:: 1.8 - .. tip:: Use this option for Confluence Data Center. @@ -194,6 +192,8 @@ Essential configuration confluence_publish_token = 'AbCdEfGhIjKlMnOpQrStUvWxY/z1234567890aBc' + .. versionadded:: 1.8 + .. _confluence_server_pass: .. confval:: confluence_server_pass @@ -239,8 +239,6 @@ Generic configuration .. confval:: confluence_add_secnumbers - .. versionadded:: 1.2 - Add section numbers to page and section titles if ``toctree`` uses the ``:numbered:`` option. By default, this is enabled: @@ -250,12 +248,12 @@ Generic configuration See also :lref:`confluence_publish_prefix`. + .. versionadded:: 1.2 + .. _confluence_code_block_theme: .. confval:: confluence_code_block_theme - .. versionadded:: 2.2 - .. note:: This option is only supported using the ``v1`` @@ -271,9 +269,9 @@ Generic configuration For configuring the theme on individual code blocks, see :ref:`class hints `. -.. confval:: confluence_default_alignment + .. versionadded:: 2.2 - .. versionadded:: 1.3 +.. confval:: confluence_default_alignment Explicitly set which alignment type to use when a default alignment value is detected. As of Sphinx 2.0+, the default alignment is set to ``center``. @@ -286,9 +284,9 @@ Generic configuration confluence_default_alignment = 'left' -.. confval:: confluence_disable_env_conf + .. versionadded:: 1.3 - .. versionadded:: 2.7 +.. confval:: confluence_disable_env_conf A boolean value to configure whether to ignore environment-provided configuration options. This extension will fallback on environment @@ -300,9 +298,9 @@ Generic configuration confluence_disable_env_conf = True -.. confval:: confluence_domain_indices + .. versionadded:: 2.7 - .. versionadded:: 1.7 +.. confval:: confluence_domain_indices A boolean or list value to configure whether or not generate domain-specific indices. If configured to a value of ``True``, all domain-specific indices @@ -319,12 +317,12 @@ Generic configuration 'py-modindex', ] + .. versionadded:: 1.7 + .. _confluence_editor: .. confval:: confluence_editor - .. versionadded:: 2.0 - .. note:: - Confluence's ``v1`` editor provides a larger support for Sphinx @@ -358,6 +356,8 @@ Generic configuration For per-document overrides, please see the :lref:`confluence_metadata`. + .. versionadded:: 2.0 + .. _confluence_header_file: .. confval:: confluence_header_file @@ -380,8 +380,6 @@ Generic configuration .. confval:: confluence_header_data - .. versionadded:: 1.9 - Takes an optional dictionary. If this value is set then ``confluence_header_file`` is interpreted as a jinja2 template with these values passed in. If this value is not set then ``confluence_header_file`` @@ -389,6 +387,8 @@ Generic configuration See also :lref:`confluence_header_file`. + .. versionadded:: 1.9 + .. _confluence_footer_file: .. confval:: confluence_footer_file @@ -411,8 +411,6 @@ Generic configuration .. confval:: confluence_footer_data - .. versionadded:: 1.9 - Takes an optional dictionary. If this value is set then ``confluence_footer_file`` is interpreted as a jinja2 template with these values passed in. If this value is not set then ``confluence_footer_file`` @@ -420,9 +418,9 @@ Generic configuration See also :lref:`confluence_header_file`. -.. confval:: confluence_include_search + .. versionadded:: 1.9 - .. versionadded:: 1.7 +.. confval:: confluence_include_search A boolean value to configure whether or not generate a search page. If configured to a value of ``True``, a search page will be created with a @@ -438,10 +436,9 @@ Generic configuration confluence_include_search = True -.. confval:: confluence_page_generation_notice - .. versionadded:: 1.7 - .. versionchanged:: 2.5 Accept a string for custom notice. + +.. confval:: confluence_page_generation_notice This option can be set with a boolean value to whether or not to generate a message at the top of each document that the page has been @@ -459,9 +456,10 @@ Generic configuration By default, this notice is disabled with a value of ``False``. -.. confval:: confluence_page_hierarchy + .. versionadded:: 1.7 + .. versionchanged:: 2.5 Accept a string for custom notice. - .. versionchanged:: 2.0 Option is enabled by default. +.. confval:: confluence_page_hierarchy A boolean value to whether or not nest pages in a hierarchical ordered. The root of all pages is typically the configured root_doc_. If a root_doc_ @@ -479,12 +477,12 @@ Generic configuration these documents will still be published and uploaded to either the configured :lref:`confluence_parent_page` or in the root of the space. + .. versionchanged:: 2.0 Option is enabled by default. + .. _confluence_prev_next_buttons_location: .. confval:: confluence_prev_next_buttons_location - .. versionadded:: 1.2 - A string value to where to include previous/next buttons (if any) based on the detected order of documents to be included in processing. Values accepted are either ``bottom``, ``both``, ``top`` or ``None``. By default, @@ -494,12 +492,12 @@ Generic configuration confluence_prev_next_buttons_location = 'top' + .. versionadded:: 1.2 + .. _confluence_secnumber_suffix: .. confval:: confluence_secnumber_suffix - .. versionadded:: 1.2 - The suffix to put after section numbers, before section name. .. code-block:: python @@ -508,9 +506,9 @@ Generic configuration See also :lref:`confluence_add_secnumbers`. -.. confval:: confluence_sourcelink + .. versionadded:: 1.2 - .. versionadded:: 1.7 +.. confval:: confluence_sourcelink Provides options to include a link to the documentation's sources at the top of each page. This can either be a generic URL or customized to link to @@ -622,10 +620,10 @@ Generic configuration 'text': 'Edit Source', } -.. confval:: confluence_use_index - .. versionadded:: 1.7 +.. confval:: confluence_use_index + A boolean value to configure whether or not generate an index page. If configured to a value of ``True``, an index page will be created. If a ``genindex`` document is registered in a documentation's toctree_, index @@ -639,10 +637,10 @@ Generic configuration confluence_use_index = True -.. confval:: singleconfluence_toctree - .. versionadded:: 1.7 +.. confval:: singleconfluence_toctree + A boolean value to configure whether or not TOC trees will remain in place when building with a ``singleconfluence`` builder. By default, this option is disabled with a value of ``False``. @@ -651,6 +649,8 @@ Generic configuration singleconfluence_toctree = True + .. versionadded:: 1.7 + Publishing configuration ------------------------ @@ -658,8 +658,6 @@ Publishing configuration .. confval:: confluence_append_labels - .. versionadded:: 1.3 - Allows a user to decide how to manage labels for an updated page. When a page update contains new labels to set, they can either be stacked on existing labels or replaced. In the event that a publisher wishes to replace @@ -676,12 +674,12 @@ Publishing configuration - :lref:`confluence_global_labels` - :lref:`confluence_metadata` + .. versionadded:: 1.3 + .. _confluence_api_mode: .. confval:: confluence_api_mode - .. versionadded:: 2.5 - Configures the API mode to use for REST requests. Certain Confluence instances support a newer version of REST APIs (e.g. Confluence Cloud). This extension will attempt to use an appropriate API mode for a @@ -697,6 +695,8 @@ Publishing configuration By default, if a Confluence Cloud configuration is detected, this extension will use ``v2``. For all other cases, the default is ``v1``. + .. versionadded:: 2.5 + .. _confluence_ask_password: .. confval:: confluence_ask_password @@ -734,8 +734,6 @@ Publishing configuration .. confval:: confluence_ask_user - .. versionadded:: 1.2 - Provides an override for an interactive shell to request publishing documents using a user provided from a shell environment. While a user is typically defined in the option ``confluence_server_user``, select @@ -747,14 +745,14 @@ Publishing configuration confluence_ask_user = False + .. versionadded:: 1.2 + .. index:: Page removal; Automatically archiving pages .. _confluence_cleanup_archive: .. confval:: confluence_cleanup_archive - .. versionadded:: 1.9 - .. warning:: Publishing individual/subset of documents with this option may lead to @@ -803,12 +801,12 @@ Publishing configuration - :lref:`confluence_cleanup_search_mode` - :lref:`confluence_publish_dryrun` + .. versionadded:: 1.9 + .. _confluence_cleanup_from_root: .. confval:: confluence_cleanup_from_root - .. versionadded:: 1.9 - A boolean value to which indicates that any cleanup attempt should be done from the root of a published root_doc_ page (instead of a configured parent page; i.e. :lref:`confluence_parent_page`). In specific publishing @@ -831,14 +829,14 @@ Publishing configuration - :lref:`confluence_cleanup_archive` - :lref:`confluence_cleanup_purge` + .. versionadded:: 1.9 + .. index:: Page removal; Automatically purging pages .. _confluence_cleanup_purge: .. confval:: confluence_cleanup_purge - .. versionadded:: 1.9 - .. warning:: Publishing individual/subset of documents with this option may lead to @@ -875,12 +873,12 @@ Publishing configuration - :lref:`confluence_cleanup_search_mode` - :lref:`confluence_publish_dryrun` + .. versionadded:: 1.9 + .. _confluence_disable_notifications: .. confval:: confluence_disable_notifications - .. versionchanged:: 2.6 Option is enabled by default. - A boolean value which explicitly disables any page update notifications (i.e. treats page updates from a publish request as minor updates). By default, notifications are disabled with a value of ``True``. @@ -895,13 +893,12 @@ Publishing configuration See also :lref:`confluence_watch`. + .. versionchanged:: 2.6 Option is enabled by default. + .. _confluence_full_width: .. confval:: confluence_full_width - .. versionadded:: 2.0 - .. versionchanged:: 2.1 Support added for Confluence's ``v1`` editor. - A boolean value to whether to publish pages using the full width of a page. By default, page widths will use their default/existing page widths with a value of ``None``. Specifying this option to ``True`` will ensure any @@ -915,12 +912,13 @@ Publishing configuration For per-document overrides, please see the :lref:`confluence_metadata`. + .. versionadded:: 2.0 + .. versionchanged:: 2.1 Support added for Confluence's ``v1`` editor. + .. _confluence_global_labels: .. confval:: confluence_global_labels - .. versionadded:: 1.3 - .. note:: If removing global labels for a documentation set that already @@ -941,6 +939,8 @@ Publishing configuration For per-document labels, please see the :lref:`confluence_metadata`. See also :lref:`confluence_append_labels`. + .. versionadded:: 1.3 + .. _confluence_parent_page: .. confval:: confluence_parent_page @@ -949,8 +949,6 @@ Publishing configuration This option cannot be used with :lref:`confluence_publish_root`. - .. versionchanged:: 1.9 Support added for accepting a page identifier. - The root page found inside the configured space (:lref:`confluence_space_key`) where published pages will be a descendant of. The parent page value is used to match either the @@ -978,12 +976,12 @@ Publishing configuration See also :lref:`confluence_publish_root`. + .. versionchanged:: 1.9 Support added for accepting a page identifier. + .. _confluence_publish_dryrun: .. confval:: confluence_publish_dryrun - .. versionadded:: 1.3 - When a user wishes to start managing a new document set for publishing, there maybe concerns about conflicts with existing content. When the dry run feature is enabled to ``True``, a publish event will not edit or remove any @@ -999,13 +997,12 @@ Publishing configuration See also :ref:`Confluence Spaces and Unique Page Names `. + .. versionadded:: 1.3 + .. _confluence_publish_postfix: .. confval:: confluence_publish_postfix - .. versionadded:: 1.2 - .. versionchanged:: 1.9 Support for the ``{hash}`` placeholder. - If set, a postfix value is added to the title of all published documents. In Confluence, page names need to be unique for a space. A postfix can be set to either: @@ -1040,6 +1037,9 @@ Publishing configuration - :lref:`confluence_ignore_titlefix_on_index` - :lref:`confluence_publish_prefix` + .. versionadded:: 1.2 + .. versionchanged:: 1.9 Support for the ``{hash}`` placeholder. + .. _confluence_publish_prefix: .. confval:: confluence_publish_prefix @@ -1068,8 +1068,6 @@ Publishing configuration .. confval:: confluence_publish_root - .. versionadded:: 1.5 - .. note:: This option cannot be used with :lref:`confluence_parent_page`. @@ -1087,12 +1085,12 @@ Publishing configuration See also :lref:`confluence_parent_page`. + .. versionadded:: 1.5 + .. _confluence_root_homepage: .. confval:: confluence_root_homepage - .. versionadded:: 1.6 - A boolean value to whether or not force the configured space's homepage to be set to the page defined by the Sphinx configuration's root_doc_. By default, the root_doc_ configuration is ignored with a value of ``False``. @@ -1101,6 +1099,8 @@ Publishing configuration confluence_root_homepage = False + .. versionadded:: 1.6 + .. _confluence_timeout: .. confval:: confluence_timeout @@ -1121,8 +1121,6 @@ Publishing configuration .. confval:: confluence_watch - .. versionadded:: 1.3 - Indicate whether or not the user publishing content will automatically watch pages for changes. In Confluence, when creating a new page or updating an existing page, the editing user will automatically watch the page. @@ -1138,13 +1136,13 @@ Publishing configuration See also :lref:`confluence_disable_notifications`. + .. versionadded:: 1.3 + Advanced publishing configuration --------------------------------- .. confval:: confluence_additional_mime_types - .. versionadded:: 1.3 - Candidate selection for images will only support the internally managed list of MIME types supported by a default Confluence instance. A custom installation or future installations of a Confluence instance may support @@ -1158,10 +1156,10 @@ Advanced publishing configuration 'image/tiff', ] -.. confval:: confluence_asset_force_standalone - .. versionadded:: 1.3 +.. confval:: confluence_asset_force_standalone + Provides an override to always publish individual assets (images, downloads, etc.) on each individual document which uses them. This extension will attempt to minimize the amount of publishing of shared assets on multiple @@ -1177,6 +1175,8 @@ Advanced publishing configuration confluence_asset_force_standalone = True + .. versionadded:: 1.3 + .. confval:: confluence_asset_override Provides an override for asset publishing to allow a user publishing to @@ -1200,8 +1200,6 @@ Advanced publishing configuration .. confval:: confluence_ca_cert - .. versionchanged:: 2.3 Support relative paths. - Provide a CA certificate to use for server certificate authentication. The value for this option can either be a file of a certificate or a path pointing to an OpenSSL-prepared directory. Refer to the @@ -1219,12 +1217,12 @@ Advanced publishing configuration - :lref:`confluence_client_cert` - :lref:`confluence_disable_ssl_validation` + .. versionchanged:: 2.3 Support relative paths. + .. _confluence_cleanup_search_mode: .. confval:: confluence_cleanup_search_mode - .. versionadded:: 2.1 - .. warning:: The ``direct`` search mode may not work on Confluence Data Center @@ -1260,6 +1258,8 @@ Advanced publishing configuration - :lref:`confluence_cleanup_archive` - :lref:`confluence_cleanup_purge` + .. versionadded:: 2.1 + .. _confluence_client_cert: .. confval:: confluence_client_cert @@ -1354,8 +1354,6 @@ Advanced publishing configuration .. confval:: confluence_ignore_titlefix_on_index - .. versionadded:: 1.3 - When configured to add a prefix or postfix onto the titles of published documents, a user may not want to have any title modifications on the index page. To prevent modifying an index page's title, this option can be set to @@ -1370,9 +1368,9 @@ Advanced publishing configuration - :lref:`confluence_publish_postfix` - :lref:`confluence_publish_prefix` -.. confval:: confluence_page_search_mode + .. versionadded:: 1.3 - .. versionadded:: 2.6 +.. confval:: confluence_page_search_mode .. note:: @@ -1396,9 +1394,9 @@ Advanced publishing configuration - ``content`` `(default)`: Pages will fetched using the ``content/`` API. - ``search``: Pages will fetched using the ``content/search/`` API. -.. confval:: confluence_parent_override_transform + .. versionadded:: 2.6 - .. versionadded:: 2.2 +.. confval:: confluence_parent_override_transform .. note:: @@ -1430,6 +1428,8 @@ Advanced publishing configuration See also :lref:`confluence_parent_page`. + .. versionadded:: 2.2 + .. confval:: confluence_proxy REST calls use the Requests_ library, which will use system-defined proxy @@ -1444,11 +1444,6 @@ Advanced publishing configuration .. confval:: confluence_publish_allowlist - .. versionadded:: 1.3 - .. versionchanged:: 2.0 An empty allow list will no longer publish any - documents. - .. versionchanged:: 2.3 Support relative paths. - .. note:: Using this option will disable the :lref:`confluence_cleanup_archive` @@ -1496,19 +1491,15 @@ Advanced publishing configuration See also :lref:`confluence_publish_denylist`. + .. versionadded:: 1.3 + .. versionchanged:: 2.0 An empty allow list will no longer publish any + documents. + .. versionchanged:: 2.3 Support relative paths. + .. _confluence_publish_debug: .. confval:: confluence_publish_debug - .. versionadded:: 1.8 - .. versionchanged:: 2.5 - - Switched from boolean to string for setting new debugging options. - - .. versionchanged:: 2.6 - - Introduce the ``headers-and-data`` option. - .. warning:: Enabling certain debugging options may reveal information such as @@ -1536,9 +1527,16 @@ Advanced publishing configuration confluence_publish_debug = 'urllib3' -.. confval:: confluence_publish_delay - .. versionadded:: 1.8 + .. versionchanged:: 2.5 + + Switched from boolean to string for setting new debugging options. + + .. versionchanged:: 2.6 + + Introduce the ``headers-and-data`` option. + +.. confval:: confluence_publish_delay Force a delay (in seconds) for any API calls made to a Confluence instance. By default, API requests will be made to a Confluence instance as soon as @@ -1551,13 +1549,12 @@ Advanced publishing configuration confluence_publish_delay = 0.25 + .. versionadded:: 1.8 + .. _confluence_publish_denylist: .. confval:: confluence_publish_denylist - .. versionadded:: 1.3 - .. versionchanged:: 2.3 Support relative paths. - .. note:: Using this option will disable the :lref:`confluence_cleanup_archive` @@ -1605,12 +1602,13 @@ Advanced publishing configuration See also :lref:`confluence_publish_allowlist`. + .. versionadded:: 1.3 + .. versionchanged:: 2.3 Support relative paths. + .. _confluence_publish_force: .. confval:: confluence_publish_force - .. versionadded:: 2.1 - A boolean value on whether or not to force publish page updates even if no changes are detected on the Confluence instance. When a page is published by this extension, a hash of the page will be stored on the @@ -1625,12 +1623,12 @@ Advanced publishing configuration confluence_publish_force = True + .. versionadded:: 2.1 + .. _confluence_publish_headers: .. confval:: confluence_publish_headers - .. versionadded:: 1.5 - A dictionary value which allows a user to pass key-value header information. This is useful for users who need to interact with a Confluence instance which expects (in a reverse proxy or the instance itself) specific header @@ -1643,9 +1641,9 @@ Advanced publishing configuration 'CUSTOM_HEADER': '', } -.. confval:: confluence_publish_intersphinx + .. versionadded:: 1.5 - .. versionadded:: 1.9 +.. confval:: confluence_publish_intersphinx A publish event will upload a generated intersphinx's inventory (`object.inv`) as an attachment to the configured root_doc_. Inventory @@ -1658,9 +1656,9 @@ Advanced publishing configuration confluence_publish_intersphinx = True -.. confval:: confluence_publish_onlynew + .. versionadded:: 1.9 - .. versionadded:: 1.3 +.. confval:: confluence_publish_onlynew A publish event from this extension will typically upload new pages or update existing pages on future attempts. In select cases, a user may not @@ -1675,12 +1673,12 @@ Advanced publishing configuration confluence_publish_onlynew = True + .. versionadded:: 1.3 + .. _confluence_publish_orphan: .. confval:: confluence_publish_orphan - .. versionadded:: 2.1 - Whether to permit the publishing of orphan pages to a Confluence space. This option must be explicitly set to ``False`` if a user wishes to not publish orphan pages for their documentation. By default, the value is set @@ -1692,12 +1690,12 @@ Advanced publishing configuration See also :lref:`confluence_publish_orphan_container`. + .. versionadded:: 2.1 + .. _confluence_publish_orphan_container: .. confval:: confluence_publish_orphan_container - .. versionadded:: 2.1 - The identifier of the page to hold orphan pages. The parent page associated to an orphan page can vary per configuration. When a user configures for a parent page/root, orphan pages will be placed under the @@ -1715,12 +1713,12 @@ Advanced publishing configuration See also :lref:`confluence_publish_orphan`. + .. versionadded:: 2.1 + .. _confluence_publish_override_api_prefix: .. confval:: confluence_publish_override_api_prefix - .. versionadded:: 2.5 - Allows a user to override the path-prefix value used for API requests. API paths are commonly prefixed, such as ``rest/api/`` for API v1 and ``api/v2/`` for API v2. However, if a user is interacting with a Confluence @@ -1748,9 +1746,9 @@ Advanced publishing configuration 'v1': '', } -.. confval:: confluence_request_session_override + .. versionadded:: 2.5 - .. versionadded:: 1.7 +.. confval:: confluence_request_session_override A hook to manipulate a Requests_ session prepared by this extension. Allows users who wish to perform advanced configuration of a session for features @@ -1763,6 +1761,8 @@ Advanced publishing configuration confluence_request_session_override = my_request_session_override + .. versionadded:: 1.7 + .. _confluence_server_auth: .. confval:: confluence_server_auth @@ -1797,8 +1797,6 @@ Advanced publishing configuration .. confval:: confluence_server_cookies - .. versionadded:: 1.2 - A dictionary value which allows a user to pass key-value cookie information for authentication purposes. This is useful for users who need to authenticate with a single sign-on (SSO) provider to access a target @@ -1812,12 +1810,12 @@ Advanced publishing configuration 'U_ID': '', } + .. versionadded:: 1.2 + .. _confluence_title_overrides: .. confval:: confluence_title_overrides - .. versionadded:: 1.3 - Allows a user to override the title value for a specific document. When documents are parsed for title values, the first title element's content will be used as the publish page's title. Select documents may not include a @@ -1843,12 +1841,9 @@ Advanced publishing configuration - :lref:`confluence_publish_prefix` - :lref:`confluence_remove_title` -.. confval:: confluence_version_comment - - .. versionadded:: 1.8 - .. versionchanged:: 2.1 + .. versionadded:: 1.3 - Support comments for first/new pages on Confluence Cloud. +.. confval:: confluence_version_comment .. note:: @@ -1861,6 +1856,11 @@ Advanced publishing configuration confluence_version_comment = 'Automatically generated.' + .. versionadded:: 1.8 + .. versionchanged:: 2.1 + + Support comments for first/new pages on Confluence Cloud. + Advanced processing configuration --------------------------------- @@ -1879,8 +1879,6 @@ Advanced processing configuration .. confval:: confluence_html_macro - .. versionadded:: 2.7 - This option will configure the HTML macro type for the ``confluence_html`` :ref:`directive `. By default, the ``html`` macro identifier is set. @@ -1891,14 +1889,14 @@ Advanced processing configuration See also the :ref:`HTML directive `. + .. versionadded:: 2.7 + .. index:: Jira; Configuring Jira servers .. _confluence_jira_servers: .. confval:: confluence_jira_servers - .. versionadded:: 1.2 - Provides a dictionary of named Jira servers to reference when using the ``jira`` or ``jira_issue`` directives. In a typical Confluence environment which is linked with a Jira instance, users do not need to take advantage of @@ -1942,12 +1940,12 @@ Advanced processing configuration - :ref:`Jira directives ` - :ref:`Jira roles ` + .. versionadded:: 1.2 + .. _confluence_lang_overrides: .. confval:: confluence_lang_overrides - .. versionadded:: 2.6 - A dictionary to override literal block-based directive language values to a Confluence supported code block macro language values. The default mapping accepts `Pygments documented language types`_ to @@ -1964,12 +1962,12 @@ Advanced processing configuration the provided language type will be transform to a default language type as if this transform was not provided. + .. versionadded:: 2.6 + .. _confluence_latex_macro: .. confval:: confluence_latex_macro - .. versionadded:: 1.8 - .. note:: Confluence does not provide stock support for LaTeX macros. @@ -2006,6 +2004,8 @@ Advanced processing configuration - :ref:`LaTeX roles ` - :doc:`guide-math` + .. versionadded:: 1.8 + .. _confluence_link_suffix: .. confval:: confluence_link_suffix @@ -2024,8 +2024,6 @@ Advanced processing configuration .. confval:: confluence_mentions - .. versionadded:: 1.9 - Provides a dictionary of key-to-value mappings which can be used with ``confluence_mention`` roles. When defining mentions, documents can reference a user's account identifier, user key or username (depending @@ -2055,9 +2053,9 @@ Advanced processing configuration - :ref:`Mention roles ` -.. confval:: confluence_navdocs_transform + .. versionadded:: 1.9 - .. versionadded:: 1.7 +.. confval:: confluence_navdocs_transform A function to override the document list used for populating navigational buttons generated from a :lref:`confluence_prev_next_buttons_location` @@ -2075,12 +2073,12 @@ Advanced processing configuration See also :lref:`confluence_prev_next_buttons_location`. + .. versionadded:: 1.7 + .. _confluence_permit_raw_html: .. confval:: confluence_permit_raw_html - .. versionadded:: 2.2 - .. caution:: Using this option is considered unsupported. This extension will @@ -2115,6 +2113,8 @@ Advanced processing configuration See also :lref:`confluence_html` directive. + .. versionadded:: 2.2 + .. _confluence_remove_title: .. confval:: confluence_remove_title @@ -2146,8 +2146,6 @@ Third-party related options .. confval:: confluence_mermaid_html_macro - .. versionadded:: 2.7 - .. warning:: This option relies on an HTML macro which is not available in a @@ -2191,13 +2189,13 @@ Third-party related options See also :lref:`confluence_html_macro`. + .. versionadded:: 2.7 + Other options ------------- .. confval:: suppress_warnings - .. versionadded:: 2.1 - This extension supports suppressing warnings using Sphinx's `suppress_warnings`_ configuration. The following includes additional warning types that may be suppressed: @@ -2207,24 +2205,24 @@ Other options - ``confluence.deprecated_develop`` -- Development deprecated warnings - ``confluence.unsupported_code_lang`` -- Unsupported code language + .. versionadded:: 2.1 + Deprecated options ------------------ .. confval:: confluence_lang_transform - .. versionchanged:: 2.6 - This option has been replaced by :lref:`confluence_lang_overrides`. -.. confval:: confluence_master_homepage + .. versionchanged:: 2.6 - .. versionchanged:: 1.6 +.. confval:: confluence_master_homepage This option has been renamed to :lref:`confluence_root_homepage`. -.. confval:: confluence_parent_page_id_check + .. versionchanged:: 1.6 - .. versionchanged:: 1.9 +.. confval:: confluence_parent_page_id_check The :lref:`confluence_parent_page` option now accepts both a page name and identifier. @@ -2241,38 +2239,40 @@ Deprecated options See also :lref:`confluence_parent_page`. -.. confval:: confluence_publish_disable_api_prefix + .. versionchanged:: 1.9 - .. versionchanged:: 2.5 +.. confval:: confluence_publish_disable_api_prefix This option has been replaced by :lref:`confluence_publish_override_api_prefix`. -.. confval:: confluence_publish_subset + .. versionchanged:: 2.5 - .. versionchanged:: 1.3 +.. confval:: confluence_publish_subset This option has been renamed to :lref:`confluence_publish_allowlist`. -.. confval:: confluence_purge_from_master + .. versionchanged:: 1.3 - .. versionchanged:: 1.6 +.. confval:: confluence_purge_from_master This option has been renamed to ``confluence_purge_from_root``, and has since been replaced with :lref:`confluence_cleanup_from_root`. -.. confval:: confluence_purge_from_root + .. versionchanged:: 1.6 - .. versionchanged:: 1.9 +.. confval:: confluence_purge_from_root This option has been renamed to :lref:`confluence_cleanup_from_root`. -.. confval:: confluence_space_name + .. versionchanged:: 1.9 - .. versionchanged:: 1.7 +.. confval:: confluence_space_name This option has been renamed to :lref:`confluence_space_key`. + .. versionchanged:: 1.7 + .. footnotes ------------------------------------------------------------------- diff --git a/doc/directives.rst b/doc/directives.rst index 9dff957f..1c7a5ea0 100644 --- a/doc/directives.rst +++ b/doc/directives.rst @@ -23,8 +23,6 @@ Common .. rst:directive:: confluence_excerpt - .. versionadded:: 2.0 - The ``confluence_excerpt`` directive allows a user to define a Confluence `Excerpt Macro`_ to help build snippets of content to be shared for other pages. For example: @@ -81,13 +79,13 @@ Common This content is reusable. + .. versionadded:: 2.0 + .. index:: Macros; Excerpt Include Macro (directive) .. index:: Excerpt Include Macro .. rst:directive:: .. confluence_excerpt_include:: [ref] - .. versionadded:: 2.0 - The ``confluence_excerpt_include`` directive allows a user to define a Confluence `Excerpt Include Macro`_ to help include snippets of content provided by excerpt macro definitions. An include macro requires an @@ -138,14 +136,14 @@ Common .. confluence_excerpt_include:: !my-excerpt-docname :nopanel: true + .. versionadded:: 2.0 + .. index:: Macros; Expand Macro (directive) .. index:: Expand Macro .. _confluence_expand-directive: .. rst:directive:: confluence_expand - .. versionadded:: 1.3 - The ``confluence_expand`` directive allows a user to define a Confluence `Expand Macro`_ to help manage the visibility of content on a page. For example: @@ -172,12 +170,12 @@ Common See also :doc:`guide-collapse`. + .. versionadded:: 1.3 + .. _confluence_html: .. rst:directive:: confluence_html - .. versionadded:: 2.7 - .. warning:: The `HTML Macro`_ is disabled by default on Confluence instances. @@ -197,14 +195,12 @@ Common See also :lref:`confluence_permit_raw_html`. + .. versionadded:: 2.7 + .. _confluence_metadata: .. rst:directive:: confluence_metadata - .. versionadded:: 1.3 - .. versionchanged:: 2.2 Added ``editor`` and ``full-width`` support. - .. versionchanged:: 2.8 Added ``guid`` support. - The ``confluence_metadata`` directive allows a user to define metadata information to be added during a publish event. This directive supports the following options: @@ -259,9 +255,11 @@ Common See also :lref:`confluence_global_labels`. -.. rst:directive:: confluence_newline + .. versionadded:: 1.3 + .. versionchanged:: 2.2 Added ``editor`` and ``full-width`` support. + .. versionchanged:: 2.8 Added ``guid`` support. - .. versionadded:: 1.7 +.. rst:directive:: confluence_newline The ``confluence_newline`` directive supports the injection of a newline in a document where seperation may be desired between inlined elements. @@ -270,9 +268,9 @@ Common .. confluence_newline:: -.. rst:directive:: confluence_toc + .. versionadded:: 1.7 - .. versionadded:: 1.9 +.. rst:directive:: confluence_toc The ``confluence_toc`` directive allows a user to define a Confluence `Table of Contents Macro`_. Users are typically recommended to use @@ -398,6 +396,8 @@ Common .. confluence_toc:: :type: flat + .. versionadded:: 1.9 + .. index:: Macros; Jira Macro (directive) .. _jira-directives: @@ -411,8 +411,6 @@ Confluence documents. .. rst:directive:: .. jira:: [jql] - .. versionadded:: 1.2 - The ``jira`` directive allows a user to build a Jira macro to be configured with a provided JQL query. For example: @@ -493,13 +491,12 @@ Confluence documents. :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d :server-name: MyAwesomeJiraServer + .. versionadded:: 1.2 .. index:: Jira; Adding a single Jira link (directive) .. rst:directive:: .. jira_issue:: [issue-id] - .. versionadded:: 1.2 - The ``jira_issue`` directive allows a user to build a Jira macro to be configured with a provided Jira key. For example: @@ -547,6 +544,8 @@ Confluence documents. :server-id: d005bcc2-ca4e-4065-8ce8-49ff5ac5857d :server-name: MyAwesomeJiraServer + .. versionadded:: 1.2 + See also :ref:`Jira roles `. .. index:: Macros; LaTeX Macro (directive) @@ -568,8 +567,6 @@ Confluence page. .. rst:directive:: .. confluence_latex:: - .. versionadded:: 1.8 - The ``confluence_latex`` directive allows a user to add LaTeX content into a document. For example: @@ -594,6 +591,8 @@ Confluence page. $\mathfrak{H}$ello world! + .. versionadded:: 1.8 + See also :ref:`LaTeX roles `. .. index:: Smart links; Directives @@ -609,8 +608,6 @@ Smart links .. rst:directive:: confluence_doc - .. versionadded:: 2.1 - The ``confluence_doc`` directive allows a user to define a link to a document that is styled with a card appearance. The directive accepts the name of a document in an absolute or relative fashion (in the same manner @@ -666,10 +663,10 @@ Smart links :card: embed :width: 50 -.. rst:directive:: confluence_link - .. versionadded:: 2.1 +.. rst:directive:: confluence_link + The ``confluence_link`` directive allows a user to define a link to a page that is styled with a card appearance. The directive accepts a URL. How Confluence renders the context of a link card will vary based on @@ -724,6 +721,8 @@ Smart links :card: embed :width: 50 + .. versionadded:: 2.1 + See also :ref:`smart link roles `. diff --git a/doc/roles.rst b/doc/roles.rst index e38fef83..58563d23 100644 --- a/doc/roles.rst +++ b/doc/roles.rst @@ -14,8 +14,6 @@ generated Confluence documents. .. rst:role:: confluence_emoticon - .. versionadded:: 1.9 - The ``confluence_emoticon`` role allows a user to build inlined emoticon macros. For example: @@ -25,6 +23,8 @@ generated Confluence documents. :confluence_emoticon:`cross`: This is incomplete. + .. versionadded:: 1.9 + .. index:: Macros; Jira Macro (role) .. _jira-roles: @@ -38,8 +38,6 @@ Confluence documents. .. rst:role:: jira - .. versionadded:: 1.7 - The ``jira`` role allows a user to build an inlined Jira macro to be configured with a provided Jira key. For example: @@ -47,6 +45,8 @@ Confluence documents. See :jira:`TEST-123` for more details. + .. versionadded:: 1.7 + See also :ref:`Jira directives `. .. index:: Macros; LaTeX Macro (role) @@ -68,8 +68,6 @@ Confluence documents. .. rst:role:: confluence_latex - .. versionadded:: 1.8 - The ``confluence_latex`` role allows a user to build inlined LaTeX content. For example: @@ -77,6 +75,8 @@ Confluence documents. This is a :confluence_latex:`$\\mathfrak{t}$est`. + .. versionadded:: 1.8 + See also :ref:`LaTeX directives `. .. index:: Macros; Mentions Macro (role) @@ -91,8 +91,6 @@ generated Confluence documents. .. rst:role:: confluence_mention - .. versionadded:: 1.9 - .. warning:: Confluence Cloud mentions should always use account identifiers; where @@ -121,6 +119,8 @@ generated Confluence documents. A user mapping table can also be configured using the :lref:`confluence_mentions` option. + .. versionadded:: 1.9 + .. index:: Smart links; Roles .. _smart-link-roles: @@ -136,8 +136,6 @@ Support for inlined smart links can be created using the following roles. .. rst:role:: confluence_doc - .. versionadded:: 2.1 - The ``confluence_doc`` role allows a user to define an inlined link to a document that is styled with a card appearance. The role accepts the name of a document in an absolute or relative fashion (in the same manner @@ -147,10 +145,10 @@ Support for inlined smart links can be created using the following roles. See :confluence_doc:`my-other-page`. -.. rst:role:: confluence_link - .. versionadded:: 2.1 +.. rst:role:: confluence_link + The ``confluence_link`` role allows a user to define an inlined link to a page that is styled with a card appearance. The role accepts a URL. How Confluence renders the context of a link card will vary based on @@ -160,6 +158,8 @@ Support for inlined smart links can be created using the following roles. See :confluence_link:`https://example.com`. + .. versionadded:: 2.1 + See also :ref:`smart link directives `. .. index:: Macros; Status Macro (role) @@ -173,8 +173,6 @@ generated Confluence documents. .. rst:role:: confluence_status - .. versionadded:: 1.9 - The ``confluence_status`` role allows a user to build inlined status macros. For example: @@ -198,6 +196,8 @@ generated Confluence documents. :confluence_status:`PASSED [green]` + .. versionadded:: 1.9 + .. index:: Strikethrough (role) .. _confluence_strike-role: @@ -209,8 +209,6 @@ generated Confluence documents. .. rst:role:: confluence_strike - .. versionadded:: 2.1 - The ``confluence_strike`` role allows a user to build inlined text that has been styled with a strikethrough. For example: @@ -218,6 +216,8 @@ generated Confluence documents. :confluence_strike:`My text` + .. versionadded:: 2.1 + See also :doc:`guide-strike`. .. references ------------------------------------------------------------------