From 680bbd576545210487264307f2b34bca3b367a98 Mon Sep 17 00:00:00 2001 From: James Knight Date: Sat, 22 Jun 2024 23:06:28 -0400 Subject: [PATCH] doc: update advanced extensions document for helpers In an attempt to improve documentation for users wanting to extend their documentation capabilities, adding translator helpers into the advanced section. Signed-off-by: James Knight --- doc/advanced-extensions.rst | 91 +++++++++++++++++++++++++++++++++---- doc/conf.py | 11 +++++ doc/configuration.rst | 1 + 3 files changed, 93 insertions(+), 10 deletions(-) diff --git a/doc/advanced-extensions.rst b/doc/advanced-extensions.rst index 915303f7..0007b75c 100644 --- a/doc/advanced-extensions.rst +++ b/doc/advanced-extensions.rst @@ -11,20 +11,16 @@ 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. +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. 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 +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 @@ -42,6 +38,81 @@ this node with Sphinx Confluence Builder: def depart_custom_node(self, node): self.body.append(self.context.pop()) +Confluence Storage Format Translator Helpers +-------------------------------------------- + +When extending this extension or adding more advanced configurations, a +series of helper calls are available for use. API calls may evolve over time +as this extension is maintained. The following methods are available for a +``ConfluenceStorageFormatTranslator`` translator. + +.. Ideally, the following entries would use `:no-index-entry:` over + `:no-index:`. However it looks like the autodocs extension does no yet + support this capability. + +.. (sorting) start off with start/end tag + +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_tag + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_tag + :no-index: + +.. (sorting) then sort by name with prefix order start/end pairs and specific calls + +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_image + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_image + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_link + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_link + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_link_body + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_link_body + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.build_ac_param + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_plain_text_body_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_plain_text_body_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_plain_text_link_body_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_plain_text_link_body_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ac_rich_text_body_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ac_rich_text_body_macro + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_adf_content + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_adf_content + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_adf_extension + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.build_adf_attribute + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_adf_extension + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_adf_node + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_adf_node + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.start_ri_attachment + :no-index: +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.end_ri_attachment + :no-index: + +.. (sorting) then others + +.. autofunction:: sphinxcontrib.confluencebuilder.storage.translator.ConfluenceStorageFormatTranslator.escape_cdata + :no-index: + .. references ------------------------------------------------------------------ .. _Sphinx.add_node: https://www.sphinx-doc.org/en/master/extdev/appapi.html#sphinx.application.Sphinx.add_node diff --git a/doc/conf.py b/doc/conf.py index a73d22ef..53fb146e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -2,6 +2,7 @@ # Copyright Sphinx Confluence Builder Contributors (AUTHORS) from docutils import nodes +from sphinx.ext.autodoc import cut_lines from sphinx.transforms.post_transforms import SphinxPostTransform import sphinxcontrib.confluencebuilder @@ -18,6 +19,11 @@ root_doc = 'contents' +extensions = [ + 'sphinx.ext.autodoc', + 'sphinx.ext.napoleon', +] + # reStructuredText string included at the end of every source rst_epilog = f''' .. |supported_confluence_ver| replace:: {supported_confluence_ver} @@ -40,6 +46,8 @@ 'toc.excluded', ] +add_module_names = False + # -- Options for HTML output ---------------------------------------------- html_theme = 'sphinx13b' @@ -125,6 +133,9 @@ def setup(app): app.add_js_file('jquery-3.6.3.min.js') app.add_js_file('version-alert.js') + # remove first line description docstrings in documentation + app.connect('autodoc-process-docstring', cut_lines(1)) + # custom directives/roles for documentation app.add_object_type('builderval', 'builderval', objname='builders', indextemplate='pair: %s; builder') diff --git a/doc/configuration.rst b/doc/configuration.rst index bdd89f40..982e8b97 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -2101,6 +2101,7 @@ Other options - ``confluence`` -- All warnings - ``confluence.deprecated`` -- Configuration deprecated warnings + - ``confluence.deprecated_develop`` -- Development deprecated warnings - ``confluence.unsupported_code_lang`` -- Unsupported code language Deprecated options