Skip to content
Snippets Groups Projects

Resolve "Updates to documentation"

Merged Reinhard Biegel requested to merge 122-updates-to-documentation into develop
178 files
+ 527
17970
Compare changes
  • Side-by-side
  • Inline
Files
178
+ 146
0
###############################################################################
# Copyright (c) 2021 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
#
# This program and the accompanying materials are made
# available under the terms of the Eclipse Public License 2.0
# which is available at https://www.eclipse.org/legal/epl-2.0/
#
# SPDX-License-Identifier: EPL-2.0
###############################################################################
import os
import shutil
from textwrap import dedent
from sphinx.directives.other import TocTree
class ARGS:
"""Default argument values"""
API_DOC_BUILD_DEACTIVATED = "off"
DEFAULT_API_DOC_BUILD = API_DOC_BUILD_DEACTIVATED
DEFAULT_API_DOC_PATH = "api"
DEFAULT_API_DOC_TITLE = "Source Code Documentation"
def api_doc_build_activated(config):
"""True if api_doc_build is NOT set to deactivated"""
return config.api_doc_build.lower() != ARGS.API_DOC_BUILD_DEACTIVATED
def purge_api_doc_path(app, config):
"""Purges the rst files from the build folder"""
api_doc_path = os.path.join(app.srcdir, config.api_doc_path)
if os.path.exists(api_doc_path):
shutil.rmtree(api_doc_path, ignore_errors=True)
def on_config_inited(app, config):
"""
Sphinx Event Hook:
Activates and configures breath and exhale if api_doc_build is active
"""
if api_doc_build_activated(config):
app.setup_extension('breathe')
app.setup_extension('exhale')
config.exhale_args = {
# These arguments are required
"containmentFolder": f"./{config.api_doc_path}",
"rootFileName": "index.rst",
"rootFileTitle": f"{config.api_doc_title}",
"doxygenStripFromPath": "../../../sim",
# Suggested optional arguments
"createTreeView": True,
# TIP: if using the sphinx-bootstrap-theme, you need
# "treeViewIsBootstrap": True,
"exhaleExecutesDoxygen": True,
"exhaleDoxygenStdin": dedent('''
INPUT = ../../../sim/src
WARN_IF_UNDOCUMENTED = NO
WARN_AS_ERROR = NO
PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS
GENERATE_HTML = NO
RECURSIVE = YES
FULL_PATH_NAMES = YES
QUIET = YES
FILE_PATTERNS = *.cpp *.h
ENABLE_PREPROCESSING = YES
MACRO_EXPANSION = YES
SKIP_FUNCTION_MACROS = NO
EXPAND_ONLY_PREDEF = NO
''')}
config.breathe_projects = {"openpass": "doxyoutput/xml"}
config.breathe_default_project = "openpass"
config.cpp_id_attributes = ['Q_DECL_IMPORT']
else:
purge_api_doc_path(app, config)
class ApiDoc(TocTree):
"""
Customized TocTree Directive `.. toctree-api::`
Enhances the regular toctree by a conditional :api-doc: entry.
If api_doc_build is active :api-doc: will be replaced by the
entry point to the api documentation such as api/index.rst
Use config values `api_doc_path` and `api_doc_title` to adjust
subdirectory and title shown in the toc, respectively.
Example:
.. toctree-api::
:caption: Developer Information
:glob:
developer_information/*
:api-doc:
"""
API_DOC_DIRECTIVE = "toctree-api"
API_DOC_TOKEN = ':api-doc:'
@property
def api_doc_active(self):
return api_doc_build_activated(self.state.document.settings.env.config)
@property
def api_doc_entry_point(self):
config = self.state.document.settings.env.config
return f'/{config.api_doc_path}/index.rst'
def _parse_conditional_api_doc(self):
"""
Scans for the API_DOC_TOKEN and transforms it if active
Returns a new list of toc entries (= self.content)
"""
toc_entries = list()
for toc_entry in self.content:
if toc_entry.strip() == self.API_DOC_TOKEN:
if self.api_doc_active:
toc_entries.append(self.api_doc_entry_point)
else:
toc_entries.append(toc_entry)
return toc_entries
def run(self):
self.content = self._parse_conditional_api_doc()
return super().run()
def setup(app):
app.connect('config-inited', on_config_inited)
app.add_directive(ApiDoc.API_DOC_DIRECTIVE, ApiDoc)
app.add_config_value(name='api_doc_build',
default=ARGS.DEFAULT_API_DOC_BUILD, rebuild='env')
app.add_config_value(name='api_doc_path',
default=ARGS.DEFAULT_API_DOC_PATH, rebuild='env')
app.add_config_value(name='api_doc_title',
default=ARGS.DEFAULT_API_DOC_TITLE, rebuild='env')
return {'version': '0.1'}
Loading