diff --git a/doc/advanced-extensions.rst b/doc/advanced-extensions.rst new file mode 100644 index 00000000..915303f7 --- /dev/null +++ b/doc/advanced-extensions.rst @@ -0,0 +1,48 @@ +Extensions +========== + +The Sphinx Confluence Builder is powered by Sphinx_. There are several +ways individual projects may extend their configuration or use other +extensions to improve the processing and generation of their documentation. + +For users new to Sphinx, it is recommended to read Sphinx's documentation +on extensions: + + | Sphinx Extensions API + | https://www.sphinx-doc.org/en/master/extdev/index.html + +This extension does not provide any significant API capabilities beyond +what is provided by Sphinx's existing API support. Developers or advanced +users are recommended to use official Sphinx API calls for any modifications +that are applicable when using the Sphinx Confluence Builder extension. +Users are welcome to inspect this extension's code for any custom tweaks +desired for their project;. While using extension specific implementation +for customization is unsupported, this extension aims to be flexible to +support users when possible. + +The following shows an example modification for a project to support a +custom node type that is not supported by this extension. Users can use +`Sphinx.add_node`_ to help register support for custom nodes. The keyword +to use for this extension is `confluence`. If another extension defines a +node `custom_node`, the following shows some example code to start supporting +this node with Sphinx Confluence Builder: + +.. code-block:: python + + def setup(app): + app.add_node( + custom_node, + confluence=(visit_custom_node, depart_custom_node), + ) + + def visit_custom_node(self, node): + self.body.append('[pre]') + self.context.append('[post]') + + def depart_custom_node(self, node): + self.body.append(self.context.pop()) + +.. references ------------------------------------------------------------------ + +.. _Sphinx.add_node: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_node +.. _Sphinx: https://www.sphinx-doc.org/ diff --git a/doc/advanced-publish-permissions.rst b/doc/advanced-publish-permissions.rst new file mode 100644 index 00000000..83c47b96 --- /dev/null +++ b/doc/advanced-publish-permissions.rst @@ -0,0 +1,27 @@ +Publishing permissions +====================== + +An account used for authentication will have the best experience with the +following permissions_ when attempting to publish to a configured space: + +- Space -- View +- Page -- Add, Delete +- Attachments -- Add, Delete + +Delete permissions are only required for environments using the +``confluence_cleanup_purge`` (:ref:`ref`) +capabilitity. + +For environments using an OAuth connector, the following scopes are required: + +.. code-block:: none + + delete:content:confluence + read:content-details:confluence + write:attachment:confluence + write:content:confluence + write:watcher:confluence + +.. references ------------------------------------------------------------------ + +.. _Permissions: https://support.atlassian.com/confluence-cloud/docs/what-are-confluence-cloud-permissions-and-restrictions/ diff --git a/doc/advanced-wiping-space.rst b/doc/advanced-wiping-space.rst new file mode 100644 index 00000000..10bffd64 --- /dev/null +++ b/doc/advanced-wiping-space.rst @@ -0,0 +1,41 @@ +.. index:: Wiping a space +.. index:: Page removal; Wiping a space + +Wiping a space +============== + +.. danger:: + + Pages removed from this call cannot be recovered without the help of an + administrator for the Confluence space which pages will be removed from. + +A command line argument ``wipe`` is available for users wishing to remove pages +from a configured space. This can be useful for users who need to clear multiple +pages which have been pushed through automation or if the Confluence instance +does not support automatically deleting page children. + +A wipe request can be started using the following: + +.. code-block:: shell-session + + $ python -m sphinxcontrib.confluencebuilder wipe --danger + ... + + Are you sure you want to continue? [y/N] y + + URL: https://intranet-wiki.example.com/ + Space: TEST + Pages: All Pages + Total pages: 250 + + Are you sure you want to REMOVE these pages? [y/N] y + + Removing pages.... done + +If a user wishes to only remove child pages of a +:ref:`configured parent page `, the option ``--parent`` +can be used: + +.. code-block:: shell + + python -m sphinxcontrib.confluencebuilder wipe --danger --parent diff --git a/doc/advanced.rst b/doc/advanced.rst index b977ab7b..d5d8c524 100644 --- a/doc/advanced.rst +++ b/doc/advanced.rst @@ -1,76 +1,9 @@ Advanced ======== -Publishing permissions ----------------------- +.. toctree:: + :maxdepth: 1 -An account used for authentication will have the best experience with the -following permissions_ when attempting to publish to a configured space: - -- Space -- View -- Page -- Add, Delete -- Attachments -- Add, Delete - -Delete permissions are only required for environments using the -``confluence_cleanup_purge`` (:ref:`ref`) -capabilitity. - -For environments using an OAuth connector, the following scopes are required: - -.. code-block:: none - - delete:content:confluence - read:content-details:confluence - write:attachment:confluence - write:content:confluence - write:watcher:confluence - -.. raw:: latex - - \newpage - -.. index:: Wiping a space -.. index:: Page removal; Wiping a space - -Wiping a space --------------- - -.. danger:: - - Pages removed from this call cannot be recovered without the help of an - administrator for the Confluence space which pages will be removed from. - -A command line argument ``wipe`` is available for users wishing to remove pages -from a configured space. This can be useful for users who need to clear multiple -pages which have been pushed through automation or if the Confluence instance -does not support automatically deleting page children. - -A wipe request can be started using the following: - -.. code-block:: shell-session - - $ python -m sphinxcontrib.confluencebuilder wipe --danger - ... - - Are you sure you want to continue? [y/N] y - - URL: https://intranet-wiki.example.com/ - Space: TEST - Pages: All Pages - Total pages: 250 - - Are you sure you want to REMOVE these pages? [y/N] y - - Removing pages.... done - -If a user wishes to only remove child pages of a -:ref:`configured parent page `, the option ``--parent`` -can be used: - -.. code-block:: shell - - python -m sphinxcontrib.confluencebuilder wipe --danger --parent - -.. references ------------------------------------------------------------------ - -.. _Permissions: https://support.atlassian.com/confluence-cloud/docs/what-are-confluence-cloud-permissions-and-restrictions/ + advanced-extensions + advanced-publish-permissions + advanced-wiping-space