Merge pull request #1026 from sphinx-contrib/adding-html-directive

Add the html confluence directive

Author: jdknight

doc/configuration.rst

@@ -2081,6 +2081,9 @@ Advanced processing configuration
 
     See also |confluence_prev_next_buttons_location|_.
 
+.. |confluence_permit_raw_html| replace:: ``confluence_permit_raw_html``
+.. _confluence_permit_raw_html:
+
 .. confval:: confluence_permit_raw_html
 
     .. versionadded:: 2.2
@@ -2117,6 +2120,8 @@ Advanced processing configuration
     or Confluence may reject the publication of Confluence document (i.e.
     failing to upload a page).
 
+    See also :lref:`confluence_html` directive.
+
 .. |confluence_remove_title| replace:: ``confluence_remove_title``
 .. _confluence_remove_title:
 

doc/directives.rst

@@ -172,6 +172,31 @@ Common
 
     See also :doc:`guide-collapse`.
 
+.. _confluence_html:
+
+.. rst:directive:: confluence_html
+
+    .. versionadded:: 2.7
+
+    .. warning::
+
+        The `HTML Macro`_ is disabled by default on Confluence instances.
+        Using this directive is only useful for users that have instances
+        where a system administrator has enabled their use.
+
+    The ``confluence_html`` directive allows a user to define a Confluence
+    `HTML Macro`_ to render HTML content on a page. For example:
+
+    .. code-block:: rst
+
+        .. confluence_html::
+
+            <h1>Header</h1>
+
+            This is an <strong>example</strong>.
+
+    See also :lref:`confluence_permit_raw_html`.
+
 .. _confluence_metadata:
 
 .. rst:directive:: confluence_metadata
@@ -699,6 +724,7 @@ See also :ref:`smart link roles <smart-link-roles>`.
 .. _Excerpt Include Macro: https://confluence.atlassian.com/doc/excerpt-include-macro-148067.html
 .. _Excerpt Macro: https://confluence.atlassian.com/doc/excerpt-macro-148062.html
 .. _Expand Macro: https://confluence.atlassian.com/doc/expand-macro-223222352.html
+.. _HTML Macro: https://confluence.atlassian.com/doc/html-macro-38273085.html
 .. _Sphinx's toctree directive: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents
 .. _Table of Contents Macro: https://support.atlassian.com/confluence-cloud/docs/insert-the-table-of-contents-macro/
 .. _directives: https://www.sphinx-doc.org/en/stable/usage/restructuredtext/directives.html

sphinxcontrib/confluencebuilder/__init__.py

@@ -10,6 +10,7 @@
 from sphinxcontrib.confluencebuilder.directives import ConfluenceExcerptDirective
 from sphinxcontrib.confluencebuilder.directives import ConfluenceExcerptIncludeDirective
 from sphinxcontrib.confluencebuilder.directives import ConfluenceExpandDirective
+from sphinxcontrib.confluencebuilder.directives import ConfluenceHtmlDirective
 from sphinxcontrib.confluencebuilder.directives import ConfluenceLatexDirective
 from sphinxcontrib.confluencebuilder.directives import ConfluenceLinkDirective
 from sphinxcontrib.confluencebuilder.directives import ConfluenceMetadataDirective
@@ -222,6 +223,8 @@ def setup(app):
     # (configuration - advanced processing)
     # Filename suffix for generated files.
     cm.add_conf('confluence_file_suffix', 'confluence')
+    # Macro configuration for Confluence-managed HTML content.
+    cm.add_conf('confluence_html_macro', 'confluence')
     # Configuration for named JIRA Servers
     cm.add_conf('confluence_jira_servers', 'confluence')
     # Translation of a raw language to code block macro language.
@@ -349,6 +352,7 @@ def confluence_builder_inited(app):
     app.add_directive('confluence_excerpt_include',
         ConfluenceExcerptIncludeDirective)
     app.add_directive('confluence_expand', ConfluenceExpandDirective)
+    app.add_directive('confluence_html', ConfluenceHtmlDirective)
     app.add_directive('confluence_latex', ConfluenceLatexDirective)
     app.add_directive('confluence_link', ConfluenceLinkDirective)
     app.add_directive('confluence_metadata', ConfluenceMetadataDirective)

sphinxcontrib/confluencebuilder/config/checks.py

@@ -316,6 +316,12 @@ def validate_configuration(builder):
 
     # ##################################################################
 
+    # confluence_html_macro
+    validator.conf('confluence_html_macro') \
+             .string()
+
+    # ##################################################################
+
     # confluence_ignore_titlefix_on_index
     validator.conf('confluence_ignore_titlefix_on_index') \
              .bool()

sphinxcontrib/confluencebuilder/directives.py

@@ -8,6 +8,7 @@
 from sphinxcontrib.confluencebuilder.nodes import confluence_expand
 from sphinxcontrib.confluencebuilder.nodes import confluence_excerpt
 from sphinxcontrib.confluencebuilder.nodes import confluence_excerpt_include
+from sphinxcontrib.confluencebuilder.nodes import confluence_html
 from sphinxcontrib.confluencebuilder.nodes import confluence_latex_block
 from sphinxcontrib.confluencebuilder.nodes import confluence_link_card
 from sphinxcontrib.confluencebuilder.nodes import confluence_metadata
@@ -165,6 +166,19 @@ def run(self):
         return [node]
 
 
+class ConfluenceHtmlDirective(Directive):
+    has_content = True
+
+    def run(self):
+        self.assert_has_content()
+        text = '\n'.join(self.content)
+
+        node = confluence_html(rawsource=text)
+
+        self.state.nested_parse(self.content, self.content_offset, node)
+        return [node]
+
+
 class ConfluenceLatexDirective(Directive):
     has_content = True
     option_spec = {

sphinxcontrib/confluencebuilder/nodes.py

@@ -102,6 +102,13 @@ class confluence_header(nodes.Decorative, nodes.Element):
     a document.
     """
 
+class confluence_html(nodes.TextElement):
+    """
+    confluence html node
+
+    A Confluence builder defined HTML node, used to help manage HTML content
+    designed for an HTML macro.
+    """
 
 class confluence_metadata(nodes.Invisible, nodes.Special, ConfluenceParams):
     """

sphinxcontrib/confluencebuilder/storage/translator.py

@@ -2513,6 +2513,21 @@ def depart_confluence_header(self, node):
                 **{'style':
                     'clear: both; padding-top: 10px; margin-bottom: 30px'}))
 
+    def visit_confluence_html(self, node):
+        html_macro = 'html'
+        if self.builder.config.confluence_html_macro:
+            html_macro = self.builder.config.confluence_html_macro
+
+        html_content = node.rawsource
+
+        self.body.append(self.start_ac_macro(node, html_macro))
+        self.body.append(self.start_ac_plain_text_body_macro(node))
+        self.body.append(self.escape_cdata(html_content))
+        self.body.append(self.end_ac_plain_text_body_macro(node))
+        self.body.append(self.end_ac_macro(node))
+
+        raise nodes.SkipNode
+
     def visit_confluence_newline(self, node):
         self.body.append(self.start_tag(
             node, 'br', suffix=self.nl, empty=True))

tests/unit-tests/datasets/html/index.rst

@@ -0,0 +1,8 @@
+:orphan:
+
+html macro
+----------
+
+.. confluence_html::
+
+    <strong>strong text</strong>

tests/unit-tests/test_config_checks.py

@@ -434,6 +434,17 @@ def test_config_check_header_file(self):
         self.config['confluence_header_file'] = relbase + 'sample-header.tpl'
         self._try_config()
 
+    def test_config_check_confluence_html_macro(self):
+        self.config['confluence_html_macro'] = ''
+        self._try_config()
+
+        self.config['confluence_html_macro'] = 'dummy'
+        self._try_config()
+
+        self.config['confluence_html_macro'] = 1
+        with self.assertRaises(ConfluenceConfigError):
+            self._try_config()
+
     def test_config_check_jira_servers(self):
         self.config['confluence_jira_servers'] = {}
         self._try_config()

tests/unit-tests/test_confluence_html.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: BSD-2-Clause
+# Copyright Sphinx Confluence Builder Contributors (AUTHORS)
+
+from bs4 import BeautifulSoup
+from bs4 import CData
+from tests.lib.parse import parse
+from tests.lib.testcase import ConfluenceTestCase
+from tests.lib.testcase import setup_builder
+
+
+class TestConfluenceHtml(ConfluenceTestCase):
+    @classmethod
+    def setUpClass(cls):
+        super().setUpClass()
+
+        cls.dataset = cls.datasets / 'html'
+
+    @setup_builder('confluence')
+    def test_storage_confluence_html_custom_macro(self):
+        config = dict(self.config)
+        config['confluence_html_macro'] = 'custom-html'
+        out_dir = self.build(self.dataset, config=config)
+
+        with parse('index', out_dir) as data:
+            html_macro = data.find('ac:structured-macro',
+                {'ac:name': 'custom-html'})
+            self.assertIsNotNone(html_macro)
+
+            plain_body = html_macro.find('ac:plain-text-body')
+            self.assertIsNotNone(plain_body)
+
+            html_macro_cdata = next(plain_body.children, None)
+            self.assertIsNotNone(html_macro_cdata)
+            self.assertTrue(isinstance(html_macro_cdata, CData))
+
+            html_macro_data = BeautifulSoup(html_macro_cdata, 'html.parser')
+
+            strong_element = html_macro_data.find('strong')
+            self.assertIsNotNone(strong_element)
+            text_contents = strong_element.text.strip()
+            self.assertIsNotNone(text_contents)
+            self.assertTrue('strong text' in text_contents)
+
+    @setup_builder('confluence')
+    def test_storage_confluence_html_default(self):
+        out_dir = self.build(self.dataset)
+
+        with parse('index', out_dir) as data:
+            html_macro = data.find('ac:structured-macro', {'ac:name': 'html'})
+            self.assertIsNotNone(html_macro)
+
+            plain_body = html_macro.find('ac:plain-text-body')
+            self.assertIsNotNone(plain_body)
+
+            html_macro_cdata = next(plain_body.children, None)
+            self.assertIsNotNone(html_macro_cdata)
+            self.assertTrue(isinstance(html_macro_cdata, CData))
+
+            html_macro_data = BeautifulSoup(html_macro_cdata, 'html.parser')
+
+            strong_element = html_macro_data.find('strong')
+            self.assertIsNotNone(strong_element)
+            text_contents = strong_element.text.strip()
+            self.assertIsNotNone(text_contents)
+            self.assertTrue('strong text' in text_contents)