add option to specify additional HTMLs in docs (#28)

jbloom · web-flow · commit 554c699ec3bd · 2024-03-07T14:05:52.000-08:00
You can now specify an `add_htmls_to_docs` variable in your `Snakefile`
that specifies additional files to include in the docs, like this:

    # add extra HTML to docs
    add_htmls_to_docs = {
        "Additional files": {
            "Example HTML file": "results/extra_htmls/example_html.html",
        },
    }

Also, `snakemake` was upgraded to 8.5.4.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,9 @@
 # CHANGELOG
 
+### version 2.2.0
+- Add the `add_htmls_to_docs` option, which can be specified in `Snakefile` to add additional HTML documentation to pipeline.
+- Update to `snakemake` 8.5.4.
+
 ### version 2.1.0
 - Add an option to specify `miscellaneous_plates` which are plates that just have their barcodes counted (addresses [this issue](https://github.com/jbloomlab/seqneut-pipeline/issues/26)).
 
diff --git a/README.md b/README.md
@@ -511,6 +511,17 @@ Looking at this documentation is a good way to QC the data and understand the re
 
 The documentation for the test example for this pipeline is at [https://jbloomlab.github.io/seqneut-pipeline/](https://jbloomlab.github.io/seqneut-pipeline/).
 
+If you want to add additional HTML files to the docs, specify a dict in the top-level `Snakefile` with the name `add_htmls_to_docs` like this:
+```
+add_htmls_to_docs = {
+    "Additional files": {
+        "Example HTML file":  "results/extra_htmls/example_html.html",
+        <other keys specifying file names and their paths>
+    },
+    <other nested dicts with a heading and then name: file key-value pairs>
+}
+```
+
 ## Test example and testing via GitHub Actions
 The [./test_example](test_example) subdirectory contains a small test example that illustrates use of the pipeline.
 
diff --git a/docs/example_html.html b/docs/example_html.html
@@ -0,0 +1,6 @@
+<!DOCTYPE html>
+<html lang="en">
+  <body>
+    Example HTML file
+  </body>
+</html>
diff --git a/docs/index.html b/docs/index.html
@@ -9,6 +9,7 @@ <h1 id="test-example-for-seqneut-pipeline">Test example for <a href="https://git
 <li><a href="#per-serum-neutralization-titers">Per-serum neutralization titers</a></li>
 <li><a href="#per-plate-counts-and-curve-fits">Per-plate counts and curve fits</a></li>
 <li><a href="#summary-of-data-dropped-during-quality-control">Summary of data dropped during quality control</a></li>
+<li><a href="#additional-files">Additional files</a></li>
 </ul>
 </div>
 <h2 id="titers-for-all-sera">Titers for all sera</h2>
@@ -26,4 +27,6 @@ <h2 id="per-plate-counts-and-curve-fits">Per-plate counts and curve fits</h2>
 <li><a href="process_plate11.html">plate11</a></li>
 </ul>
 <h2 id="summary-of-data-dropped-during-quality-control">Summary of data dropped during quality control</h2>
-<p><a href="aggregate_qc_drops.html">Notebook summarizing QC drops</a></p>
+<p><a href="aggregate_qc_drops.html">Notebook summarizing QC drops</a></p>
+<h2 id="additional-files">Additional files</h2>
+<p><a href="example_html.html">Example HTML file</a></p>
diff --git a/environment.yml b/environment.yml
@@ -17,7 +17,7 @@ dependencies:
   - python=3.11
   - ruamel.yaml=0.18.5
   - snakefmt
-  - snakemake=8.0.1
+  - snakemake=8.5.4
   - ruff
   - pip:
     - dms_variants==1.5.0
diff --git a/scripts/build_docs.py b/scripts/build_docs.py
@@ -46,6 +46,11 @@
     f"[Notebook summarizing QC drops]({os.path.basename(copied_files[snakemake.input.qc_drops_html])})",
 ]
 
+for heading, heading_d in snakemake.params.add_htmls_to_docs.items():
+    md_text += ["", f"## {heading}"]
+    for name, fname in heading_d.items():
+        md_text.append(f"[{name}]({os.path.basename(copied_files[fname])})")
+
 md_text = "\n".join(md_text)
 
 print(f"Rendering the following markdown text:\n\n{md_text}\n\n")
diff --git a/seqneut-pipeline.smk b/seqneut-pipeline.smk
@@ -48,6 +48,12 @@ if "miscellaneous_plates" in config:
 else:
     miscellaneous_plates = {}
 
+# define `add_htmls_to_docs` if not already defined.
+try:
+    add_htmls_to_docs
+except NameError:  # if not defined
+    add_htmls_to_docs = {}
+
 
 # --- Snakemake rules -------------------------------------------------------------------
 
@@ -228,6 +234,7 @@ rule notebook_to_html:
 rule build_docs:
     """Build the HTML documentation."""
     input:
+        lambda wc: [f for d in add_htmls_to_docs.values() for f in d.values()],
         titers_chart=rules.aggregate_titers.output.titers_chart,
         serum_titers_htmls=lambda wc: expand(
             "results/sera/{serum}/{serum}_titers.html",
@@ -244,6 +251,10 @@ rule build_docs:
         description=config["description"],
         sera=lambda wc: list(sera_plates()),
         plates=list(plates),
+        add_htmls_to_docs=lambda wc: {
+            key: {key2: str(val2) for (key2, val2) in val.items()}
+            for (key, val) in add_htmls_to_docs.items()
+        },
     conda:
         "environment.yml"
     log:
diff --git a/test_example/Snakefile b/test_example/Snakefile
@@ -1,6 +1,7 @@
 """Top-level ``snakemake`` file that runs analysis."""
 
 import os
+import textwrap
 
 
 configfile: "config.yml"
@@ -12,3 +13,33 @@ include: os.path.join(config["seqneut-pipeline"], "seqneut-pipeline.smk")
 rule all:
     input:
         seqneut_pipeline_outputs,
+
+
+rule make_extra_html_for_docs:
+    """Write example HTML for docs."""
+    output:
+        html="results/extra_htmls/example_html.html",
+    log:
+        "results/logs/make_extra_html_for_docs.txt",
+    run:
+        with open(output.html, "w") as f:
+            f.write(
+                textwrap.dedent(
+                    """\
+                    <!DOCTYPE html>
+                    <html lang="en">
+                      <body>
+                        Example HTML file
+                      </body>
+                    </html>
+                    """
+                )
+            )
+
+
+# add extra HTML to docs
+add_htmls_to_docs = {
+    "Additional files": {
+        "Example HTML file": "results/extra_htmls/example_html.html",
+    },
+}
