Merge pull request #914 from sphinx-contrib/doc-updates

Documentation updates (tweaks and macro guide)

doc/conf.py

@@ -6,7 +6,7 @@
 import sphinxcontrib.confluencebuilder
 
 project = 'Sphinx Confluence Builder'
-copyright = '2023 Sphinx Confluence Builder Contributors'
+copyright = '2024 Sphinx Confluence Builder Contributors'
 author = 'Sphinx Confluence Builder Contributors'
 version = sphinxcontrib.confluencebuilder.__version__
 release = sphinxcontrib.confluencebuilder.__version__

doc/features.rst

@@ -38,14 +38,23 @@ Type                    Notes
 `footnotes`_            Supported
 `highlights`_           Supported
 `hyperlink targets`_    Supported
-`images`_               Supported
+`images`_               Limited support.
+
+                        When using a Confluence v2 editor, images cannot be
+                        inlined and SVGs may not render as expected.
 `inline markup`_        Supported
 `list-table`_           Supported
 `literal blocks`_       Supported
 `math`_                 Supported with additional system tools.
 
                         Requires a LaTeX and dvipng/dvisvgm installation.
-`parsed literal block`_ Supported
+                        When using a Confluence v2 editor, images cannot be
+                        offset to be aligned in a paragraph.
+`parsed literal block`_ Limited support.
+
+                        When using a Confluence v2 editor, literal blocks
+                        cannot be parsed and the contents will be placed
+                        inside a code macro.
 `option lists`_         Supported
 `pull-quote`_           Supported
 `raw`_                  Supported.
@@ -84,14 +93,17 @@ Type                    Notes
                         ``emphasize-lines`` and ``lines`` which are not
                         supported in the Confluence markup. The code block macro
                         only supports a simple line numbers (configurable with
-                        the ``linenos`` option).
+                        the ``linenos`` option; Confluence v1 editor only).
 
                         When the ``class`` attribute contains ``collapse``, the
                         macro will be configured to be collapsed.
 `deprecated`_           Supported
 `download`_             Supported
 `glossary`_             Supported
-`hlist`_                Supported
+`hlist`_                Limited support.
+
+                        When using a Confluence v2 editor, the maximum columns
+                        for an hlist is three.
 `manpage`_              Supported
 `production list`_      Supported
 `toctree`_              Supported
@@ -137,11 +149,7 @@ Type                              Notes
                                   When building with publishing enabled, this
                                   extension will generate an ``objects.inv``
                                   inventory file which can be used by other
-                                  documentation sets. At this time, only
-                                  document names and standard references have
-                                  been tested. If a type of reference does not
-                                  work or yields unexpected results, please
-                                  report the issue with an example.
+                                  documentation sets.
 `sphinx.ext.jsmath`_              Unsupported.
 
                                   Confluence does not support the injection of

doc/guide-confluence-macros.rst

@@ -0,0 +1,68 @@
+.. index:: Confluence Macros
+
+Confluence Macros
+=================
+
+The Confluence Builder extension may attempt to support various stock
+Confluence macros through the use of custom :doc:`directives <directives>`
+or :doc:`roles <roles>`. However, not all macros will have a markup defined
+for them with this extension. Some macros may not have a graceful way to
+be used in documentation, a stock macro has yet to have a directive/role
+created or the macro is provided by a third-party vendor.
+
+.. note::
+
+    Typically, third-party vendor macros are not added into this
+    extension. Exceptions may be made for free addons. However, this
+    extension's main goal is to focus on supporting stock macros.
+
+If a stock Confluence macro does not have a directive/role created for it,
+users are welcome to submit a pull request to support the macro or create
+an issue outlining a desire for one. For developers wishing to support a
+third-party macro, it is recommended that developers create a custom
+extension providing support for this macro that can integrate with the
+Confluence Builder extension.
+
+That all being said, users looking to use macros that do not have a
+directive/role define can add any custom macro using the `raw`_ directive.
+Consider the following examples. A user can add a `"Cheese" macro`_ using
+the following in a reStructuredText document:
+
+.. code-block:: rst
+
+    .. raw:: confluence_storage
+
+        <ac:structured-macro ac:name="cheese" ac:macro-id="5d87ef61-1fcf-4d30-8d3b-82305e13233a" />
+
+Or create an `"Info" macro`_  in a Markdown document:
+
+.. code-block:: md
+
+    ```{raw} confluence_storage
+    <ac:structured-macro ac:name="info" ac:macro-id="ecc1aad7-f2f5-4b75-86d1-786370e6d499">
+        <ac:rich-text-body>
+            <p>Test</p>
+        </ac:rich-text-body>
+    </ac:structured-macro>
+    ```
+
+Try adding either of these example into a document to observe their results.
+
+Steps
+-----
+
+To add a custom macro available on a Confluence instance, perform the
+following steps:
+
+1. Creating a new page on the Confluence instance
+2. Add the specific macro to be captured on the page and saving
+3. Selecting the page's option menu and selecting "View Storage format"
+4. Look for the ``ac:structured-macro`` tags in the storage format
+5. Copy the tags and place them into a raw-directive in the documentation
+
+
+.. references ------------------------------------------------------------------
+
+.. _raw: https://docutils.sourceforge.io/docs/ref/rst/directives.html#raw-data-pass-through
+.. _"Cheese" macro: https://confluence.atlassian.com/doc/cheese-macro-154632825.html
+.. _"Info" macro: https://confluence.atlassian.com/doc/info-tip-note-and-warning-macros-51872369.html

doc/guides.rst

@@ -9,5 +9,6 @@ the Confluence Builder extension in a Sphinx-enabled environment.
 
     guide-class-hints
     guide-collapse
+    guide-confluence-macros
     guide-math
     guide-ci