Skip to content

plugin ¤

This module contains the mkdocs_coverage plugin.

MkDocsCoveragePlugin ¤

Bases: BasePlugin

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

on_files ¤

on_files(
    files: Files, config: Config, **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 (Config) –

    The MkDocs config object.

  • **kwargs (Any) –

    Additional arguments passed by MkDocs.

Returns:

  • Files

    The modified files collection.

Source code in src/mkdocs_coverage/plugin.py
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 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
def on_files(self, files: Files, config: Config, **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.
    """
    covindex = "covindex.html" if config["use_directory_urls"] else f"{self.config['page_name']}/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
    tempdir = mkdtemp()
    page_name = self.config["page_name"] + ".md"
    tempfile = Path(tempdir) / page_name
    with tempfile.open("w") as fp:
        fp.write(page_contents)
    files.append(
        File(
            page_name,
            str(tempfile.parent),
            config["site_dir"],
            config["use_directory_urls"],
        ),
    )
    return files

on_post_build ¤

on_post_build(config: Config, **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 (Config) –

    The MkDocs config object.

  • **kwargs (Any) –

    Additional arguments passed by MkDocs.

Source code in src/mkdocs_coverage/plugin.py
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
def on_post_build(self, config: Config, **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.config["page_name"]
    tmp_index = site_dir / ".coverage-tmp.html"

    if config["use_directory_urls"]:
        shutil.move(coverage_dir / "index.html", tmp_index)
    else:
        shutil.move(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(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()))