def main():
parser = argparse.ArgumentParser(
prog='sphinx-build-confluence',
add_help=False,
description='Sphinx extension to output Atlassian Confluence content.',
)
parser.add_argument('action', nargs='?')
parser.add_argument('--color',
default='auto',
action='store_const',
const='yes')
parser.add_argument('--help', '-h', action='store_true')
parser.add_argument('--no-color',
'-N',
dest='color',
action='store_const',
const='no')
parser.add_argument('--verbose', '-V', action='count', default=0)
parser.add_argument('--version',
action='version',
version='%(prog)s ' + version)
parser.add_argument('--work-dir')
args, _ = parser.parse_known_args()
if args.help:
print(usage())
sys.exit(0)
if args.color == 'no' or (args.color == 'auto'
and 'MSYSTEM' not in os.environ
and not color_terminal()):
nocolor()
# pre-load logging support if sphinx is not loaded (to prevent blank lines)
logger.initialize(preload=True)
# invoke a desired command mainline
if args.action == 'report':
rv = report_main(parser)
elif args.action == 'wipe':
rv = wipe_main(parser)
else:
rv = build_main(parser)
return rv
def main():
parser = argparse.ArgumentParser(
prog='sphinx-build-confluence',
add_help=False,
description='Sphinx extension to output Atlassian Confluence content.')
parser.add_argument('action', nargs='?')
parser.add_argument('--help', '-h', action='store_true')
parser.add_argument('--no-color', '-N', dest='color')
parser.add_argument('--verbose', '-V', action='count', default=0)
parser.add_argument('--version',
action='version',
version='%(prog)s ' + version)
parser.add_argument('--work-dir')
args, _ = parser.parse_known_args()
if args.help:
print(usage())
sys.exit(0)
logger.initialize(preload=True)
if args.color == 'no' or (args.color == 'auto' and not color_terminal()):
nocolor()
# disable color (on windows) by default when using virtualenv since it
# appears to be causing issues
elif getattr(sys, 'base_prefix', sys.prefix) != sys.prefix:
if sys.platform == 'win32':
nocolor()
# invoke a desired command mainline
if args.action == 'report':
rv = report_main(parser)
elif args.action == 'wipe':
rv = wipe_main(parser)
else:
rv = build_main(parser)
return rv
def setup(app):
ConfluenceLogger.initialize()
app.require_sphinx('1.8')
app.add_builder(ConfluenceBuilder)
app.add_builder(ConfluenceReportBuilder)
app.add_builder(SingleConfluenceBuilder)
# Images defined by data uri schemas can be resolved into generated images
# after a document's post-transformation stage. After a document's doctree
# has been resolved, re-check for any images that have been translated.
def assetsDocTreeResolvedHook(app, doctree, docname):
app.builder.assets.processDocument(doctree, docname, True)
def builderInitedHook(app):
if type(app.builder) == ConfluenceBuilder:
app.connect('doctree-resolved', assetsDocTreeResolvedHook)
app.connect('builder-inited', builderInitedHook)
# 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)
for transform in app.registry.get_post_transforms():
if transform.__name__ == 'MathNodeMigrator':
app.registry.get_post_transforms().remove(transform)
break
# ##########################################################################
"""(configuration - essential)"""
"""Enablement of publishing."""
app.add_config_value('confluence_publish', None, False)
"""API key/password to login to Confluence API with."""
app.add_config_value('confluence_server_pass', None, False)
"""URL of the Confluence instance to publish to."""
app.add_config_value('confluence_server_url', None, False)
"""Username to login to Confluence API with."""
app.add_config_value('confluence_server_user', None, False)
"""Confluence Space to publish to."""
app.add_config_value('confluence_space_name', None, False)
"""(configuration - generic)"""
"""Add page and section numbers if doctree has :numbered: option"""
app.add_config_value('confluence_add_secnumbers', None, False)
"""Default alignment for tables, figures, etc."""
app.add_config_value('confluence_default_alignment', None, 'env')
"""File to get page header information from."""
app.add_config_value('confluence_header_file', None, False)
"""File to get page footer information from."""
app.add_config_value('confluence_footer_file', None, False)
"""Enablement of the maximum document depth (before inlining)."""
app.add_config_value('confluence_max_doc_depth', None, False)
"""Enablement of publishing pages into a hierarchy from a master toctree."""
app.add_config_value('confluence_page_hierarchy', None, False)
"""Show previous/next buttons (bottom, top, both, None)."""
app.add_config_value('confluence_prev_next_buttons_location', None, False)
"""Suffix to put after section numbers, before section name"""
app.add_config_value('confluence_secnumber_suffix', None, False)
"""(configuration - publishing)"""
"""Request for publish password to come from interactive session."""
app.add_config_value('confluence_ask_password', None, False)
"""Request for publish username to come from interactive session."""
app.add_config_value('confluence_ask_user', None, False)
"""Explicitly prevent auto-generation of titles for titleless documents."""
app.add_config_value('confluence_disable_autogen_title', None, False)
"""Explicitly prevent page notifications on update."""
app.add_config_value('confluence_disable_notifications', None, False)
"""Define a series of labels to apply to all published pages."""
app.add_config_value('confluence_global_labels', None, False)
"""Enablement of configuring master as space's homepage."""
app.add_config_value('confluence_master_homepage', None, False)
"""Root/parent page's name to publish documents into."""
app.add_config_value('confluence_parent_page', None, False)
"""Perform a dry run of publishing to inspect what publishing will do."""
app.add_config_value('confluence_publish_dryrun', None, '')
"""Publish only new content (no page updates, etc.)."""
app.add_config_value('confluence_publish_onlynew', None, '')
"""Postfix to apply to title of published pages."""
app.add_config_value('confluence_publish_postfix', None, False)
"""Prefix to apply to published pages."""
app.add_config_value('confluence_publish_prefix', None, False)
"""Enablement of purging legacy child pages from a parent page."""
app.add_config_value('confluence_purge', None, False)
"""Enablement of purging legacy child pages from a master page."""
app.add_config_value('confluence_purge_from_master', None, False)
"""docname-2-title dictionary for title overrides."""
app.add_config_value('confluence_title_overrides', None, 'env')
"""Timeout for network-related calls (publishing)."""
app.add_config_value('confluence_timeout', None, False)
"""Whether or not new content should be watched."""
app.add_config_value('confluence_watch', None, False)
"""(configuration - advanced publishing)"""
"""Register additional mime types to be selected for image candidates."""
app.add_config_value('confluence_additional_mime_types', None, False)
"""Whether or not labels will be appended instead of overwriting them."""
app.add_config_value('confluence_append_labels', None, False)
"""Forcing all assets to be standalone."""
app.add_config_value('confluence_asset_force_standalone', None, False)
"""Tri-state asset handling (auto, force push or disable)."""
app.add_config_value('confluence_asset_override', None, False)
"""File/path to Certificate Authority"""
app.add_config_value('confluence_ca_cert', None, False)
"""Path to client certificate to use for publishing"""
app.add_config_value('confluence_client_cert', None, False)
"""Password for client certificate to use for publishing"""
app.add_config_value('confluence_client_cert_pass', None, False)
"""Disable SSL validation with Confluence server."""
app.add_config_value('confluence_disable_ssl_validation', None, False)
"""Ignore adding a titlefix on the index document."""
app.add_config_value('confluence_ignore_titlefix_on_index', None, False)
"""Root/parent page's identifier to publish documents into."""
app.add_config_value('confluence_parent_page_id_check', None, False)
"""Proxy server needed to communicate with Confluence server."""
app.add_config_value('confluence_proxy', None, False)
"""Subset of documents which are allowed to be published."""
app.add_config_value('confluence_publish_allowlist', None, False)
"""Subset of documents which are denied to be published."""
app.add_config_value('confluence_publish_denylist', None, False)
"""Authentication passthrough for Confluence REST interaction."""
app.add_config_value('confluence_server_auth', None, False)
"""Cookie(s) to use for Confluence REST interaction."""
app.add_config_value('confluence_server_cookies', None, False)
"""(configuration - advanced processing)"""
"""Filename suffix for generated files."""
app.add_config_value('confluence_file_suffix', None, False)
"""Translation of docname to a filename."""
app.add_config_value('confluence_file_transform', None, False)
"""Configuration for named JIRA Servers"""
app.add_config_value('confluence_jira_servers', None, True)
"""Translation of a raw language to code block macro language."""
app.add_config_value('confluence_lang_transform', None, False)
"""Link suffix for generated files."""
app.add_config_value('confluence_link_suffix', None, False)
"""Translation of docname to a (partial) URI."""
app.add_config_value('confluence_link_transform', None, False)
"""Remove a detected title from generated documents."""
app.add_config_value('confluence_remove_title', None, False)
"""(configuration - undocumented)"""
"""Enablement for aggressive descendents search (for purge)."""
app.add_config_value('confluence_adv_aggressive_search', None, False)
"""Enablement of the children macro for hierarchy mode."""
app.add_config_value('confluence_adv_hierarchy_child_macro', None, False)
"""List of node types to ignore if no translator support exists."""
app.add_config_value('confluence_adv_ignore_nodes', None, False)
"""Unknown node handler dictionary for advanced integrations."""
app.add_config_value('confluence_adv_node_handler', None, '')
"""List of optional features/macros/etc. restricted for use."""
app.add_config_value('confluence_adv_restricted', None, False)
"""Enablement of tracing processed data."""
app.add_config_value('confluence_adv_trace_data', None, False)
"""Do not cap sections to a maximum of six (6) levels."""
app.add_config_value('confluence_adv_writer_no_section_cap', None, False)
"""(configuration - deprecated)"""
# replaced by confluence_publish_allowlist
app.add_config_value('confluence_publish_subset', None, False)
# ##########################################################################
"""JIRA directives"""
"""Adds the custom nodes needed for JIRA directives"""
if not docutils.is_node_registered(jira):
app.add_node(jira)
if not docutils.is_node_registered(jira_issue):
app.add_node(jira_issue)
"""Wires up the directives themselves"""
app.add_directive('jira', JiraDirective)
app.add_directive('jira_issue', JiraIssueDirective)
"""Confluence directives"""
"""Adds the custom nodes needed for Confluence directives"""
if not docutils.is_node_registered(confluence_metadata):
app.add_node(confluence_metadata)
"""Wires up the directives themselves"""
app.add_directive('confluence_expand', ConfluenceExpandDirective)
app.add_directive('confluence_metadata', ConfluenceMetadataDirective)
# hook onto configuration initialization to finalize its state before
# passing it to the builder (e.g. handling deprecated options)
app.connect('config-inited', handle_config_inited)
# inject the compatible autosummary nodes if the extension is loaded
def inject_autosummary_notes_hook(app):
for ext in app.extensions.values():
if ext.name == 'sphinx.ext.autosummary':
add_autosummary_nodes(app)
break
app.connect('builder-inited', inject_autosummary_notes_hook)
# 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. This applies for
# Sphinx 1.8 and higher which math support is embedded; for older versions,
# users will need to explicitly load 'sphinx.ext.mathbase'.
if (imgmath is not None
and 'sphinx.ext.imgmath' not in app.config.extensions):
imgmath.setup(app)
return {
'version': __version__,
'parallel_read_safe': True,
'parallel_write_safe': True,
}
def setup(app):
ConfluenceLogger.initialize()
app.require_sphinx('1.8')
app.add_builder(ConfluenceBuilder)
app.add_builder(ConfluenceReportBuilder)
app.add_builder(SingleConfluenceBuilder)
# register this extension's locale
package_dir = path.abspath(path.dirname(__file__))
locale_dir = path.join(package_dir, 'locale')
app.add_message_catalog(MESSAGE_CATALOG_NAME, locale_dir)
# ##########################################################################
# (configuration - essential)
# Enablement of publishing.
app.add_config_value('confluence_publish', None, '')
# PAT to authenticate to Confluence API with.
app.add_config_value('confluence_publish_token', None, '')
# API key/password to login to Confluence API with.
app.add_config_value('confluence_server_pass', None, '')
# URL of the Confluence instance to publish to.
app.add_config_value('confluence_server_url', None, '')
# Username to login to Confluence API with.
app.add_config_value('confluence_server_user', None, '')
# Confluence Space to publish to.
app.add_config_value('confluence_space_key', None, '')
# (configuration - generic)
# Add page and section numbers if doctree has :numbered: option
app.add_config_value('confluence_add_secnumbers', None, 'env')
# Default alignment for tables, figures, etc.
app.add_config_value('confluence_default_alignment', None, 'env')
# Enablement of a generated domain index documents
app.add_config_value('confluence_domain_indices', None, '')
# File to get page header information from.
app.add_config_value('confluence_header_file', None, 'env')
# File to get page footer information from.
app.add_config_value('confluence_footer_file', None, 'env')
# Enablement of a generated search documents
app.add_config_value('confluence_include_search', None, '')
# Enablement of the maximum document depth (before inlining).
app.add_config_value('confluence_max_doc_depth', None, 'env')
# Enablement of a "page generated" notice.
app.add_config_value('confluence_page_generation_notice', None, 'env')
# Enablement of publishing pages into a hierarchy from a root toctree.
app.add_config_value('confluence_page_hierarchy', None, False)
# Show previous/next buttons (bottom, top, both, None).
app.add_config_value('confluence_prev_next_buttons_location', None, 'env')
# Suffix to put after section numbers, before section name
app.add_config_value('confluence_secnumber_suffix', None, 'env')
# Enablement of a "Edit/Show Source" reference on each document
app.add_config_value('confluence_sourcelink', None, 'env')
# Enablement of a generated index document
app.add_config_value('confluence_use_index', None, '')
# Enablement for toctrees for singleconfluence documents.
app.add_config_value('singleconfluence_toctree', None, 'singleconfluence')
# (configuration - publishing)
# Request for publish password to come from interactive session.
app.add_config_value('confluence_ask_password', None, '')
# Request for publish username to come from interactive session.
app.add_config_value('confluence_ask_user', None, '')
# Explicitly prevent auto-generation of titles for titleless documents.
app.add_config_value('confluence_disable_autogen_title', None, '')
# Explicitly prevent page notifications on update.
app.add_config_value('confluence_disable_notifications', None, '')
# Define a series of labels to apply to all published pages.
app.add_config_value('confluence_global_labels', None, '')
# Enablement of configuring root as space's homepage.
app.add_config_value('confluence_root_homepage', None, '')
# Parent page's name or identifier to publish documents under.
app.add_config_value('confluence_parent_page', None, '')
# Perform a dry run of publishing to inspect what publishing will do.
app.add_config_value('confluence_publish_dryrun', None, '')
# Publish only new content (no page updates, etc.).
app.add_config_value('confluence_publish_onlynew', None, '')
# Postfix to apply to title of published pages.
app.add_config_value('confluence_publish_postfix', None, 'env')
# Prefix to apply to published pages.
app.add_config_value('confluence_publish_prefix', None, 'env')
# Root page's identifier to publish documents into.
app.add_config_value('confluence_publish_root', None, '')
# Enablement of purging legacy child pages from a parent page.
app.add_config_value('confluence_purge', None, '')
# Enablement of purging legacy child pages from a root page.
app.add_config_value('confluence_purge_from_root', None, '')
# docname-2-title dictionary for title overrides.
app.add_config_value('confluence_title_overrides', None, 'env')
# Timeout for network-related calls (publishing).
app.add_config_value('confluence_timeout', None, '')
# Whether or not new content should be watched.
app.add_config_value('confluence_watch', None, '')
# (configuration - advanced publishing)
# Register additional mime types to be selected for image candidates.
app.add_config_value('confluence_additional_mime_types', None, 'env')
# Whether or not labels will be appended instead of overwriting them.
app.add_config_value('confluence_append_labels', None, '')
# Forcing all assets to be standalone.
app.add_config_value('confluence_asset_force_standalone', None, 'env')
# Tri-state asset handling (auto, force push or disable).
app.add_config_value('confluence_asset_override', None, '')
# File/path to Certificate Authority
app.add_config_value('confluence_ca_cert', None, '')
# Path to client certificate to use for publishing
app.add_config_value('confluence_client_cert', None, '')
# Password for client certificate to use for publishing
app.add_config_value('confluence_client_cert_pass', None, '')
# Disable SSL validation with Confluence server.
app.add_config_value('confluence_disable_ssl_validation', None, '')
# Ignore adding a titlefix on the index document.
app.add_config_value('confluence_ignore_titlefix_on_index', None, 'env')
# Parent page's identifier to publish documents under.
app.add_config_value('confluence_parent_page_id_check', None, '')
# Proxy server needed to communicate with Confluence server.
app.add_config_value('confluence_proxy', None, '')
# Subset of documents which are allowed to be published.
app.add_config_value('confluence_publish_allowlist', None, '')
# Enable debugging for publish requests.
app.add_config_value('confluence_publish_debug', None, '')
# Duration (in seconds) to delay each API request.
app.add_config_value('confluence_publish_delay', None, '')
# Subset of documents which are denied to be published.
app.add_config_value('confluence_publish_denylist', None, '')
# Disable adding `rest/api` to REST requests.
app.add_config_value('confluence_publish_disable_api_prefix', None, '')
# Header(s) to use for Confluence REST interaction.
app.add_config_value('confluence_publish_headers', None, '')
# Manipulate a requests instance.
app.add_config_value('confluence_request_session_override', None, '')
# Authentication passthrough for Confluence REST interaction.
app.add_config_value('confluence_server_auth', None, '')
# Cookie(s) to use for Confluence REST interaction.
app.add_config_value('confluence_server_cookies', None, '')
# Comment added to confluence version history.
app.add_config_value('confluence_version_comment', None, '')
# (configuration - advanced processing)
# Filename suffix for generated files.
app.add_config_value('confluence_file_suffix', None, 'env')
# Translation of docname to a filename.
app.add_config_value('confluence_file_transform', None, 'env')
# Configuration for named JIRA Servers
app.add_config_value('confluence_jira_servers', None, 'env')
# Translation of a raw language to code block macro language.
app.add_config_value('confluence_lang_transform', None, 'env')
# Macro configuration for Confluence-managed LaTeX content.
app.add_config_value('confluence_latex_macro', None, 'env')
# Link suffix for generated files.
app.add_config_value('confluence_link_suffix', None, 'env')
# Translation of docname to a (partial) URI.
app.add_config_value('confluence_link_transform', None, 'env')
# Mappings for documentation mentions to Confluence keys.
app.add_config_value('confluence_mentions', None, 'env')
# Inject navigational hints into the documentation.
app.add_config_value('confluence_navdocs_transform', None, '')
# Remove a detected title from generated documents.
app.add_config_value('confluence_remove_title', None, 'env')
# (configuration - undocumented)
# Enablement for aggressive descendents search (for purge).
app.add_config_value('confluence_adv_aggressive_search', None, '')
# List of node types to ignore if no translator support exists.
app.add_config_value('confluence_adv_ignore_nodes', None, '')
# Unknown node handler dictionary for advanced integrations.
app.add_config_value('confluence_adv_node_handler', None, '')
# Enablement of permitting raw html blocks to be used in storage format.
app.add_config_value('confluence_adv_permit_raw_html', None, 'env')
# List of optional features/macros/etc. restricted for use.
app.add_config_value('confluence_adv_restricted', None, 'env')
# Enablement of tracing processed data.
app.add_config_value('confluence_adv_trace_data', None, '')
# Do not cap sections to a maximum of six (6) levels.
app.add_config_value('confluence_adv_writer_no_section_cap', None, 'env')
# (configuration - deprecated)
# replaced by confluence_root_homepage
app.add_config_value('confluence_master_homepage', None, '')
# replaced by confluence_publish_allowlist
app.add_config_value('confluence_publish_subset', None, '')
# replaced by confluence_purge_from_root
app.add_config_value('confluence_purge_from_master', None, '')
# replaced by confluence_space_key
app.add_config_value('confluence_space_name', None, '')
# ##########################################################################
# hook onto configuration initialization to finalize its state before
# passing it to the builder (e.g. handling deprecated options)
app.connect('config-inited', handle_config_inited)
# hook on a builder initialization event, to perform additional
# configuration required when a user is using a confluence builder
app.connect('builder-inited', confluence_builder_inited)
return {
'version': __version__,
'parallel_read_safe': True,
'parallel_write_safe': True,
}
