Merge pull request #826 from sphinx-contrib/maintenance-2023-07-14

Maintenance (2023-07-14)
sphinx-contrib · Jul 14, 2023 · 11a5545 · 11a5545
2 parents 7cf31f9 + 134266b
commit 11a5545
Show file tree

Hide file tree

Showing 16 changed files with 231 additions and 149 deletions.
diff --git a/AUTHORS b/AUTHORS
@@ -1,5 +1,7 @@
+Aleksandr Musorin <aleksandr.musorin@semrush.com>
 Anthony Shaw <anthony.p.shaw@gmail.com>
 Anton <box4android@gmail.com>
+Brian Pandola <bpandola@gmail.com>
 Colin Starner <colin.starner@gmail.com>
 Daniel Gray <dg.dan.b@gmail.com>
 Dave Finke <dave.finke@artisancells.com>
@@ -24,6 +26,7 @@ Michał Sochoń <kaszpir@gmail.com>
 Paul D.Smith <paul@pauldsmith.org.uk>
 Pawel Limanowka <plimanowka@gmail.com>
 Richard Vodden <richard@humanisingautonomy.com>
+Sydney Jones <sydney.u.jones@gmail.com>
 Thomas Malcher <malcher@student.tugraz.at>
 Toni Ruža <toni.ruza@gmail.com>
 Tsvi Mostovicz <ttmost@gmail.com>

diff --git a/CHANGES.rst b/CHANGES.rst
@@ -4,8 +4,11 @@ Development
 * Fixed ``confluence_full_width`` issues on Confluence server/DC
 * Fixed issue where using ``confluence_full_width`` breaks an editor selection
 * Fixed re-publishing issues when certain options change (e.g. parent page)
+* Improve support when using the sphinxcontrib-video extension
+* Introduce the ``confluence_permit_raw_html`` option
 * Support configuring the theme on generated code block macros
 * Support page-specific editor and full-width overrides
+* Support page-specific parent identifier overrides when publishing
 
 2.1.1 (2023-05-19)
 ==================

diff --git a/babel b/babel
diff --git a/doc/_themes/sphinx13b/static/sphinx13b.css b/doc/_themes/sphinx13b/static/sphinx13b.css
@@ -368,7 +368,7 @@ table.right td {
     border: 1px solid #ccc;
 }
 
-div.admonition, div.warning {
+div.admonition {
     font-size: 0.9em;
     margin: 1em 0 1em 0;
     border: 1px solid #86989B;
@@ -381,33 +381,32 @@ div.admonition p:last-child {
     padding-bottom: 8px;
 }
 
-div.admonition > p, div.warning > p {
+div.admonition > p {
     margin: 0.5em 1em 0.5em 1em;
     padding: 0;
 }
 
 div.admonition > pre,
-div.admonition > div > div.highlight > pre,
-div.warning > pre,
-div.warning > div > div.highlight > pre {
+div.admonition > div > div.highlight > pre  {
     background-color: #fcfcfc;
     margin: 0.4em 1em 0.4em 1em;
 }
 
-div.admonition > p.admonition-title,
-div.warning > p.admonition-title {
+div.admonition > p.admonition-title {
     margin-top: 0.5em;
     font-weight: bold;
 }
 
-div.warning {
+div.attention {
+    border: 1px solid #9d9d27;
+}
+
+div.caution, div.warning {
     border: 1px solid #940000;
 }
 
 div.admonition > ul,
-div.admonition > ol,
-div.warning > ul,
-div.warning > ol {
+div.admonition > ol {
     margin: 0.1em 0.5em 0.5em 3em;
     padding: 0;
 }

diff --git a/doc/features.rst b/doc/features.rst
@@ -25,10 +25,7 @@ Type                    Notes
 `bullet lists`_         Supported
 `citations`_            Supported
 `compound paragraph`_   Supported
-`container`_            Limited support.
-
-                        Confluence markup does not permit the use of the
-                        ``class`` attribute for tags.
+`container`_            Supported
 `csv-table`_            Supported
 `definition lists`_     Supported
 `enumerated lists`_     Limited support.
@@ -61,7 +58,7 @@ Type                    Notes
 `transitions`_          Supported
 ======================= =====
 
-*(note: directive options "class" and "name" are ignored as they are not
+*(note: directive options "class" and "name" are mostly ignored as they are not
 supported in a Confluence format document)*
 
 Sphinx markup
@@ -120,15 +117,7 @@ each of these extensions:
 ================================= =====
 Type                              Notes
 ================================= =====
-`sphinx.ext.autodoc`_             Supported*.
-
-                                  While support for autodocs has been included
-                                  in this extension, only a limited amount of
-                                  examples and testing has been done to verify
-                                  its capabilities. If an issue is observed when
-                                  using an autodoc feature, please confirm an
-                                  expected result using an ``html`` build then
-                                  report the issue.
+`sphinx.ext.autodoc`_             Supported
 `sphinx.ext.autosectionlabel`_    Supported
 `sphinx.ext.autosummary`_         Supported
 `sphinx.ext.coverage`_            N/A

diff --git a/lint b/lint
@@ -0,0 +1,6 @@
+#!/usr/bin/env sh
+#
+# This is a helper script used to only invoke a subset of test environments
+# associated to linting.
+
+exec tox -e flake8,pylint
diff --git a/ruff.toml b/ruff.toml
@@ -0,0 +1,48 @@
+select = [
+    'ALL',
+]
+
+ignore = [
+    # various translator/role/etc. definitions may not use all/any arguments
+    'ARG001',
+    'ARG002',
+    # we are a bit complex for now
+    'C90',
+    # ignore pydocstyle
+    'D',
+    # ignore pyupgrade since python 2.7 is supported
+    'E501',
+    # ignore eradicate since spdx ids and parenthesis are false flagged
+    'ERA001',
+    # imports are sorted lexicographically in this project
+    'FBT002',
+    # imports are sorted lexicographically in this project
+    'I001',
+    # permit import aliases with case changes
+    'N812',
+    'N813',
+    # prevent false-positives with pandas checks
+    'PD',
+    # project uses unittest module
+    'PT',
+    # single quotes are preferred in this project
+    'Q000',
+    'Q001',
+    # use of asserts are acceptable for this extension
+    'S101',
+    # some formats are preferred for code readability
+    'SIM102',
+    # ignore flake8-print since we support/expect printing
+    'T20',
+]
+
+[per-file-ignores]
+'sphinxcontrib\confluencebuilder\nodes.py' = [
+    # node classes follow docutils/Sphinx casing convention
+    'N801',
+]
+
+'sphinxcontrib\confluencebuilder\roles.py' = [
+    # role functions follow Sphinx casing convention
+    'N802',
+]
diff --git a/sphinxcontrib/confluencebuilder/__init__.py b/sphinxcontrib/confluencebuilder/__init__.py
@@ -330,7 +330,20 @@ def confluence_builder_inited(app):
     app.add_role('confluence_strike', ConfluenceStrikeRole)
     app.add_role('jira', JiraRole)
 
-    # inject compatible autosummary nodes if the extension is available/loaded
+    # other
+    confluence_autosummary_support(app)
+    confluence_imgmath_support(app)
+    confluence_remove_mathnodemigrator(app)
+
+
+def confluence_autosummary_support(app):
+    """
+    inject compatible autosummary nodes if the extension is available/loaded
+
+    Args:
+        app: the sphinx application
+    """
+
     if autosummary:
         for ext in app.extensions.values():
             if ext.name == 'sphinx.ext.autosummary':
@@ -358,18 +371,36 @@ def confluence_builder_inited(app):
                 )
                 break
 
-    # lazy bind sphinx.ext.imgmath to provide configuration options
-    #
-    # If 'sphinx.ext.imgmath' is not already explicitly loaded, bind it into the
-    # setup process to a configurer can use the same configuration options
-    # outlined in the sphinx.ext.imgmath in this extension.
+
+def confluence_imgmath_support(app):
+    """
+    lazy bind sphinx.ext.imgmath to provide configuration options
+
+    If 'sphinx.ext.imgmath' is not already explicitly loaded, bind it into the
+    setup process to a configurer can use the same configuration options
+    outlined in the sphinx.ext.imgmath in this extension.
+
+    Args:
+        app: the sphinx application
+    """
+
     if imgmath is not None:
         if 'sphinx.ext.imgmath' not in app.config.extensions:
             imgmath.setup(app)
 
-    # remove math-node-migration post-transform as this extension manages both
-    # future and legacy math implementations (removing this transform removes
-    # a warning notification to the user)
+
+def confluence_remove_mathnodemigrator(app):
+    """
+    remove math-node-migration post-transform
+
+    Remove math-node-migration post-transform as this extension manages both
+    future and legacy math implementations (removing this transform removes
+    a warning notification to the user)
+
+    Args:
+        app: the sphinx application
+    """
+
     for transform in app.registry.get_post_transforms():
         if transform.__name__ == 'MathNodeMigrator':
             app.registry.get_post_transforms().remove(transform)

diff --git a/sphinxcontrib/confluencebuilder/builder.py b/sphinxcontrib/confluencebuilder/builder.py
@@ -46,7 +46,7 @@ class ConfluenceBuilder(Builder):
     allow_parallel = True
     default_translator_class = ConfluenceStorageFormatTranslator
     name = 'confluence'
-    format = 'confluence_storage'
+    format = 'confluence_storage'  # noqa: A003
     supported_image_types = ConfluenceSupportedImages()
     supported_linkcode = True
     supported_remote_images = True
@@ -227,7 +227,7 @@ def get_outdated_docs(self):
                 srcmtime = path.getmtime(sourcename)
                 if srcmtime > targetmtime:
                     yield docname
-            except EnvironmentError:
+            except OSError:
                 # source doesn't exist anymore
                 pass
 
@@ -362,7 +362,7 @@ def prepare_writing(self, docnames):
             nav_docnames.remove('search')
 
         if self.domain_indices:
-            for indexname, indexdata in self.domain_indices.items():
+            for indexname in self.domain_indices:
                 if indexname in nav_docnames:
                     nav_docnames.remove(indexname)
 
@@ -480,7 +480,7 @@ def write_doc(self, docname, doctree):
                 with open(outfilename, 'w', encoding='utf-8') as file:
                     if self.writer.output:
                         file.write(self.writer.output)
-            except (IOError, OSError) as err:
+            except OSError as err:
                 self.warn(f'error writing file {outfilename}: {err}')
 
     def publish_doc(self, docname, output):
@@ -599,7 +599,7 @@ def _prepare_page_data(self, docname, output):
             data['labels'].extend(self.config.confluence_global_labels)
 
         if 'labels' in metadata:
-            data['labels'].extend([v for v in metadata['labels']])
+            data['labels'].extend(list(metadata['labels']))
 
         return data
 
@@ -765,11 +765,10 @@ def finish(self):
                 docfile = path.join(self.outdir, self.file_transform(docname))
 
                 try:
-                    with open(docfile, 'r', encoding='utf-8') as file:
+                    with open(docfile, encoding='utf-8') as file:
                         output = file.read()
                         self.publish_doc(docname, output)
-
-                except (IOError, OSError) as err:
+                except OSError as err:
                     self.warn(f'error reading file {docfile}: {err}')
 
             self.info('building intersphinx... ', nonl=(not self._verbose))
@@ -800,7 +799,7 @@ def to_asset_name(asset):
                     with open(absfile, 'rb') as file:
                         output = file.read()
                         self.publish_asset(key, docname, output, type_, hash_)
-                except (IOError, OSError) as err:
+                except OSError as err:
                     self.warn(f'error reading asset {key}: {err}')
 
             self.publish_cleanup()
@@ -903,7 +902,7 @@ def _generate_special_document(self, docname, generator):
                 try:
                     with open(fname, encoding='utf-8') as file:
                         header_template_data = file.read() + '\n'
-                except (IOError, OSError) as err:
+                except OSError as err:
                     self.warn(f'error reading file {fname}: {err}')
 
                 # if no data is supplied, the file is plain text
@@ -925,7 +924,7 @@ def _generate_special_document(self, docname, generator):
                 try:
                     with open(fname, encoding='utf-8') as file:
                         footer_template_data = file.read() + '\n'
-                except (IOError, OSError) as err:
+                except OSError as err:
                     self.warn(f'error reading file {fname}: {err}')
 
                 # if no data is supplied, the file is plain text
@@ -943,7 +942,7 @@ def _generate_special_document(self, docname, generator):
                 f.write(self._cached_header_data)
                 generator(self, docname, f)
                 f.write(self._cached_footer_data)
-        except (IOError, OSError) as err:
+        except OSError as err:
             self.warn('error writing file %s: %s', docname, err)
 
     def _get_doctree(self, docname):