Merge pull request #982 from sphinx-contrib/add-doc-on-extended-sphinx

Add advanced extensions document

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/

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<confluence_cleanup_purge>`)
+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/

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 <confluence_parent_page>`, the option ``--parent``
+can be used:
+
+.. code-block:: shell
+
+    python -m sphinxcontrib.confluencebuilder wipe --danger --parent

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<confluence_cleanup_purge>`)
-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 <confluence_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