From 7522de2608dc2aeafb51e1348f4bcdb911bbd918 Mon Sep 17 00:00:00 2001 From: jbloom Date: Thu, 7 Mar 2024 13:56:48 -0800 Subject: [PATCH] add option to specify additional HTMLs in docs 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. --- CHANGELOG.md | 4 ++++ README.md | 11 +++++++++++ docs/example_html.html | 6 ++++++ docs/index.html | 5 ++++- environment.yml | 2 +- scripts/build_docs.py | 5 +++++ seqneut-pipeline.smk | 11 +++++++++++ test_example/Snakefile | 31 +++++++++++++++++++++++++++++++ 8 files changed, 73 insertions(+), 2 deletions(-) create mode 100644 docs/example_html.html diff --git a/CHANGELOG.md b/CHANGELOG.md index c7d46c9..7f80ac4 100644 --- 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 index da185aa..bf8c12d 100644 --- 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", + + }, + +} +``` + ## 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 new file mode 100644 index 0000000..050ba72 --- /dev/null +++ b/docs/example_html.html @@ -0,0 +1,6 @@ + + + + Example HTML file + + diff --git a/docs/index.html b/docs/index.html index bb05a20..61a294e 100644 --- a/docs/index.html +++ b/docs/index.html @@ -9,6 +9,7 @@

Test example for Per-serum neutralization titers
  • Per-plate counts and curve fits
  • Summary of data dropped during quality control
    • +
  • Additional files

    • Titers for all sera

    @@ -26,4 +27,6 @@

    Per-plate counts and curve fits

  • plate11

    • Summary of data dropped during quality control

    -

    Notebook summarizing QC drops

    \ No newline at end of file +

    Notebook summarizing QC drops

    +

    Additional files

    +

    Example HTML file

    \ No newline at end of file diff --git a/environment.yml b/environment.yml index 44b5dec..3eaa46b 100644 --- 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 index 46356a0..7b13927 100644 --- 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 index 5e5683e..c42682f 100644 --- 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 index 524300e..bb39b05 100644 --- 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( + """\ + + + + Example HTML file + + + """ + ) + ) + + +# add extra HTML to docs +add_htmls_to_docs = { + "Additional files": { + "Example HTML file": "results/extra_htmls/example_html.html", + }, +}