Skip to content

plugin ¤

This module contains the mkdocs_coverage plugin.

Classes:

MkDocsCoverageConfig ¤

Bases: Config

Configuration options for the plugin.

MkDocsCoveragePlugin ¤

MkDocsCoveragePlugin()

Bases: BasePlugin[MkDocsCoverageConfig]

The MkDocs plugin to integrate the coverage HTML report in the site.

Methods:

  • on_files –

    Add the coverage page to the navigation.

  • on_post_build –

    Copy the coverage HTML report into the site directory.

Source code in src/mkdocs_coverage/plugin.py 
37
38
39
40
def __init__(self) -> None:
    """Initialize the plugin."""
    super().__init__()
    self.page_path: str = ""

on_files ¤

on_files(
    files: Files, config: MkDocsConfig, **kwargs: Any
) -> Files

Add the coverage page to the navigation.

Hook for the on_files event. This hook is used to add the coverage page to the navigation, using a temporary file.

Parameters:

  • files (Files) –

    The files collection.

  • config (MkDocsConfig) –

    The MkDocs config object.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed by MkDocs.

Returns:

  • Files –

    The modified files collection.

Source code in src/mkdocs_coverage/plugin.py 
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
def on_files(self, files: Files, config: MkDocsConfig, **kwargs: Any) -> Files:  # noqa: ARG002
    """Add the coverage page to the navigation.

    Hook for the [`on_files` event](https://www.mkdocs.org/user-guide/plugins/#on_files).
    This hook is used to add the coverage page to the navigation, using a temporary file.

    Arguments:
        files: The files collection.
        config: The MkDocs config object.
        **kwargs: Additional arguments passed by MkDocs.

    Returns:
        The modified files collection.
    """
    page_name = self.config.page_name
    page_path: str
    if page_name is not None:
        warnings.warn(
            "The 'page_name' configuration option is deprecated and will be removed in a future release. "
            "Use the 'page_path' configuration option instead.",
            DeprecationWarning,
            stacklevel=1,
        )
        page_path = page_name
    else:
        page_path = self.config.page_path
    self.page_path = page_path
    covindex = "covindex.html" if config.use_directory_urls else f"{page_path}/covindex.html"

    style = textwrap.dedent(
        """
        <style>
        article h1, article > a, .md-sidebar--secondary {
            display: none !important;
        }
        </style>
        """,
    )

    iframe = textwrap.dedent(
        f"""
        <iframe
            id="coviframe"
            src="{covindex}"
            frameborder="0"
            scrolling="no"
            onload="resizeIframe();"
            width="100%">
        </iframe>
        """,
    )

    script = textwrap.dedent(
        """
        <script>
        var coviframe = document.getElementById("coviframe");

        function resizeIframe() {
            coviframe.style.height = coviframe.contentWindow.document.documentElement.offsetHeight + 'px';
        }

        coviframe.contentWindow.document.body.onclick = function() {
            coviframe.contentWindow.location.reload();
        }
        </script>

        """,
    )
    page_contents = style + iframe + script
    files.append(
        File.generated(
            config=config,
            src_uri=page_path + ".md",
            content=page_contents,
        ),
    )
    return files

on_post_build ¤

on_post_build(config: MkDocsConfig, **kwargs: Any) -> None

Copy the coverage HTML report into the site directory.

Hook for the on_post_build event.

Rename index.html into covindex.html. Replace every occurrence of index.html by covindex.html in the HTML files.

Parameters:

  • config (MkDocsConfig) –

    The MkDocs config object.

  • **kwargs (Any, default: {} ) –

    Additional arguments passed by MkDocs.

Source code in src/mkdocs_coverage/plugin.py 
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def on_post_build(self, config: MkDocsConfig, **kwargs: Any) -> None:  # noqa: ARG002
    """Copy the coverage HTML report into the site directory.

    Hook for the [`on_post_build` event](https://www.mkdocs.org/user-guide/plugins/#on_post_build).

    Rename `index.html` into `covindex.html`.
    Replace every occurrence of `index.html` by `covindex.html` in the HTML files.

    Arguments:
        config: The MkDocs config object.
        **kwargs: Additional arguments passed by MkDocs.
    """
    site_dir = Path(config.site_dir)
    coverage_dir = site_dir / self.page_path
    tmp_index = site_dir / ".coverage-tmp.html"

    if config.use_directory_urls:
        shutil.move(str(coverage_dir / "index.html"), tmp_index)
    else:
        shutil.move(str(coverage_dir.with_suffix(".html")), tmp_index)

    shutil.rmtree(str(coverage_dir), ignore_errors=True)
    try:
        shutil.copytree(self.config.html_report_dir, str(coverage_dir))
    except FileNotFoundError:
        log.warning(f"No such HTML report directory: {self.config.html_report_dir}")
        return

    shutil.move(str(coverage_dir / "index.html"), coverage_dir / "covindex.html")

    if config.use_directory_urls:
        shutil.move(str(tmp_index), coverage_dir / "index.html")
    else:
        shutil.move(str(tmp_index), coverage_dir.with_suffix(".html"))

    for html_file in coverage_dir.iterdir():
        if html_file.suffix == ".html" and html_file.name != "index.html":
            html_file.write_text(re.sub(r'href="index\.html"', 'href="covindex.html"', html_file.read_text()))