diff --git a/doc/conf.py b/doc/conf.py index 4fbfcf89..ec6fd65e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -16,7 +16,6 @@ import subprocess import sys -import mlx.traceability from mlx.traceability import report_warning, __version__ pkg_version = __version__ @@ -141,7 +140,7 @@ # Add any paths that contain custom static files (such as style sheets) here, # relative to this directory. They are copied after the builtin static files, # so a file named "default.css" will overwrite the builtin "default.css". -html_static_path = [os.path.join(os.path.dirname(mlx.traceability.__file__), 'assets'), '_static'] +html_static_path = ['_static'] # If not '', a 'Last updated on:' timestamp is inserted at every page bottom, # using the given strftime format. diff --git a/doc/configuration.rst b/doc/configuration.rst index 6d4eab3a..caf953b0 100644 --- a/doc/configuration.rst +++ b/doc/configuration.rst @@ -4,28 +4,15 @@ Configuration ============= -The *conf.py* file contains the documentation configuration for your project. This file needs to be equipped in order -to configure the traceability plugin. +In your Sphinx project's ``conf.py`` file, add ``mlx.traceability`` to the list of enabled extensions: -First the plugin needs to be enabled in the *extensions* variable: - -.. code-block:: bash +.. code-block:: python extensions = [ - 'mlx.traceability', ... + 'mlx.traceability', ] -Second the path to the static javascript assets needs to be added to the sphinx ``html_static_path`` -variable. - -.. code-block:: bash - - import os - import mlx.traceability - - html_static_path = [os.path.join(os.path.dirname(mlx.traceability.__file__), 'assets')] - .. _traceability_config_attributes: ---------------- diff --git a/mlx/traceability/traceability.py b/mlx/traceability/traceability.py index e4ebdafb..097a3e43 100644 --- a/mlx/traceability/traceability.py +++ b/mlx/traceability/traceability.py @@ -11,6 +11,7 @@ from re import fullmatch, match import natsort +import shutil from docutils import nodes from docutils.parsers.rst import directives from requests import Session @@ -18,6 +19,7 @@ from sphinx.errors import NoUri from sphinx.roles import XRefRole from sphinx.util.nodes import make_refnode +from sphinx.util.osutil import ensuredir from .__traceability_version__ import __version__ as version from .traceable_attribute import TraceableAttribute @@ -43,15 +45,15 @@ ItemInfo = namedtuple('ItemInfo', 'attr_val mr_id') -def generate_color_css(app, hyperlink_colors): +def generate_color_css(class_names, hyperlink_colors, css_path): """ Generates CSS file that defines the colors for each hyperlink state for each configured regex. Args: - app: Sphinx application object to use. + class_names (dict): Mapping of colors to CSS class identifiers. hyperlink_colors (dict): Dictionary with regex strings as keys and list/tuple of strings as values. + css_path (str): Location of the CSS file to create """ - class_names = app.config.traceability_class_names - with open(path.join(path.dirname(__file__), 'assets', 'hyperlink_colors.css'), 'w') as css_file: + with open(css_path, 'w') as css_file: for regex, colors in hyperlink_colors.items(): colors = tuple(colors) if len(colors) > 3: @@ -214,9 +216,14 @@ def perform_consistency_check(app, env): fname = app.config.traceability_json_export_path env.traceability_collection.export(fname) - if app.config.traceability_hyperlink_colors: - app.add_css_file('hyperlink_colors.css') - generate_color_css(app, app.config.traceability_hyperlink_colors) + if app.config.traceability_hyperlink_colors and app.builder.format == "html": + colors_filename = 'hyperlink_colors.css' + assets_dir = path.join(app.outdir, '_static') + ensuredir(assets_dir) + app.add_css_file(colors_filename) + generate_color_css(app.config.traceability_class_names, + app.config.traceability_hyperlink_colors, + path.join(assets_dir, colors_filename)) regex = app.config.traceability_checklist.get('checklist_item_regex') if regex is not None and app.config.traceability_checklist['has_checklist_items']: @@ -479,7 +486,19 @@ def setup(app): # Javascript and stylesheet for the tree-view app.add_js_file('https://cdn.rawgit.com/aexmachina/jquery-bonsai/master/jquery.bonsai.js') app.add_css_file('https://cdn.rawgit.com/aexmachina/jquery-bonsai/master/jquery.bonsai.css') - app.add_js_file(f'traceability-{version}.min.js') + + # Source local resources and register them for copying + js_filename = f'traceability-{version}.min.js' + app.add_js_file(js_filename) + + def copy_html_assets(app, exception): + if app.builder.format == 'html' and not exception: + shutil.copyfile( + path.join(path.dirname(__file__), 'assets', js_filename), + path.join(app.outdir, '_static', js_filename) + ) + + app.connect('build-finished', copy_html_assets) # Since Sphinx 6, jquery isn't bundled anymore and we need to ensure that # the sphinxcontrib-jquery extension is enabled. diff --git a/mlx/traceability/traceable_base_node.py b/mlx/traceability/traceable_base_node.py index bc1b82a8..ef35b6a8 100644 --- a/mlx/traceability/traceable_base_node.py +++ b/mlx/traceability/traceable_base_node.py @@ -103,7 +103,7 @@ def make_internal_item_ref(self, app, item_id): # change text color if item_id matches a regex in traceability_hyperlink_colors colors = self._find_colors_for_class(app.config.traceability_hyperlink_colors, item_id) - if colors: + if colors and app.builder.format == "html": class_name = app.config.traceability_class_names[colors] newnode['classes'].append(class_name) if text_on_hover_node and not isinstance(app.builder, LaTeXBuilder):