Deploying to gh-pages from @ add568c 🚀

Boehringer-Ingelheim · Jan 28, 2025 · 1c67452 · 1c67452
1 parent 4d4e423
commit 1c67452
Show file tree

Hide file tree

Showing 33 changed files with 308 additions and 530 deletions.
diff --git a/CHANGELOG.html b/CHANGELOG.html
@@ -11,12 +11,12 @@
 <meta property="og:type" content="website" />
 <meta property="og:url" content="CHANGELOG.html" />
 <meta property="og:site_name" content="Project name not set" />
-<meta property="og:description" content="All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.[Unreleased]: Documentation: Various do..." />
+<meta property="og:description" content="All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.[Unreleased]: Documentation: Update doc..." />
 <meta property="og:image:width" content="1146" />
 <meta property="og:image:height" content="600" />
 <meta property="og:image" content="/_images/social_previews/summary_CHANGELOG_48d2abeb.png" />
 <meta property="og:image:alt" content="All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning..." />
-<meta name="description" content="All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.[Unreleased]: Documentation: Various do..." />
+<meta name="description" content="All notable changes to this project will be documented in this file. The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.[Unreleased]: Documentation: Update doc..." />
 <meta name="twitter:card" content="summary_large_image" />
 
     <title>Changelog &#8212; dso-core</title>
@@ -53,7 +53,7 @@
   <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="_static/documentation_options.js?v=a2eea54d"></script>
+    <script src="_static/documentation_options.js?v=974b7fd0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -67,7 +67,7 @@
     <link rel="prev" title="Configuration" href="cli_configuration.html" />
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <meta name="docsearch:language" content="en"/>
-  <meta name="docsearch:version" content="0.1.dev1+g8c1d840" />
+  <meta name="docsearch:version" content="0.1.dev1+gadd568c" />
   </head>
 
 
@@ -159,7 +159,6 @@
 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/templates.html">Project and stage templates</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/params_files.html">Configuration files</a></li>
-<li class="toctree-l1"><a class="reference internal" href="user_guide/dvc.html">DVC integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/pre_commit.html">pre-commit integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/uv.html"><code class="docutils literal notranslate"><span class="pre">uv</span></code> integration</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="user_guide/linting.html">Linting</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
@@ -430,7 +429,7 @@ <h2>[Unreleased]<a class="headerlink" href="#unreleased" title="Link to this hea
 <section id="documentation">
 <h3>Documentation<a class="headerlink" href="#documentation" title="Link to this heading">#</a></h3>
 <ul class="simple">
-<li><p>Various documentation updates, working towards the first public version of the docs.</p></li>
+<li><p>Update documentation, finalizing the most important sections of the user guide.</p></li>
 </ul>
 </section>
 </section>

diff --git a/_images/dso-quarto-disclaimer.png b/_images/dso-quarto-disclaimer.png
diff --git a/_images/dso-quarto-watermark.png b/_images/dso-quarto-watermark.png
diff --git a/_images/social_previews/summary_user_guide_dvc_f9c275cb.png b/_images/social_previews/summary_user_guide_dvc_f9c275cb.png
diff --git a/_images/social_previews/summary_user_guide_quarto_0ac4d104.png b/_images/social_previews/summary_user_guide_quarto_0ac4d104.png
diff --git a/_images/social_previews/summary_user_guide_quarto_2f4d4872.png b/_images/social_previews/summary_user_guide_quarto_2f4d4872.png
diff --git a/_sources/getting_started.md b/_sources/getting_started.md
@@ -122,6 +122,8 @@ By default, a Quarto stage includes the following `cmd` section in the `dvc.yaml
       - dso exec quarto .
 ```
 
+`dso exec quarto` provides additional features such as pre-run scripts and watermarking. For more information see [here](user_guide/quarto.md).
+
 #### Bash Stage
 
 A Bash stage, by default, does not include an additional script. Bash code can be directly embedded in the `dvc.yaml` file:

diff --git a/_sources/index.md b/_sources/index.md
@@ -10,7 +10,6 @@
 getting_started.md
 user_guide/templates.md
 user_guide/params_files.md
-user_guide/dvc.md
 user_guide/pre_commit.md
 user_guide/uv.md
 user_guide/linting.md

diff --git a/_sources/user_guide/dvc.md b/_sources/user_guide/dvc.md
diff --git a/_sources/user_guide/quarto.md b/_sources/user_guide/quarto.md
@@ -1,5 +1,119 @@
 # Quarto integration
 
-Here we describe how DSO integrates with quarto (`dso exec quarto`, watermarking, ...)
+DSO integrates with [quarto](https://quarto.org/) for authoring reproducible analysis reports.
+Quarto supports both Python and R through Jupyter notebooks (`ipynb`) or quarto markdown (`qmd`) files.
 
-TODO
+DSO provides a wrapper script
+
+```bash
+dso exec quarto
+```
+
+to render a quarto stage that provides additional convenience features:
+
+-   specify quarto configuration in `params.in.yaml` (and benefit from [templating and inheritance](params_files.md#inheritance)).
+-   automatically place HTML report in the `resport` directory of the stage
+-   automatically create an `output` directory before running the quarto script
+-   execute a pre-run script to setup the environment
+-   possibility to add a disclaimer text at the top of each report
+-   possibility to add watermarks to all plots
+
+To benefit from the seamless quarto integration, simply start off with one of the [quarto templates](templates.md#available-templates) provided by `dso create stage`.
+
+## Quarto configuration
+
+Quarto projects can be [configured using a `_quarto.yml` file](https://quarto.org/docs/projects/quarto-projects.html#project-metadata).
+To consolidate all configuration in a single place and to benefit from dso's [hierarchical configuration system](params_files.md#inheritance), we support that quarto configuration can instead be specified in the `dso.quarto` field of a
+`params.in.yaml` file. When running `dso exec quarto`, the corresponding `_quarto.yml` file is dynamically generated
+and removed again after completion.
+
+**`params.in.yaml`**
+
+```yaml
+dso:
+    quarto:
+        before_script: "" # bash snippet to execute before running `dso exec quarto`, use this to setup environment modules etc.
+        author:
+            # please add a complete list of authors. If some authors only contributed to a certain workpackage/stage
+            # you can add the dso.quarto.author section in the respective params.in.yaml and they will be merged.
+            - name: Jane Doe
+              affiliations:
+                  - Example Department
+        format:
+            html:
+                fig-format: svg
+                toc: true
+                code-fold: true
+                embed-resources: true
+        page-layout: full
+        execute:
+            warning: true
+            message: false
+        date: now
+        date-format: YYYY-MMM-DD
+```
+
+The `dso.quarto` section supports any configuration specified in the [quarto documentation](https://quarto.org/docs/projects/quarto-projects.html#project-metadata). Additionally, there are DSO-specific configuration fields that are detailled
+in the next sections:
+
+## Pre-run script
+
+Sometimes it may be required to run a script or bash snippet to setup the environment before running quarto.
+This can be achieved by adding a `dso.quarto.before_script` field to the `params.in.yaml` file.
+
+For instance, you could use the following snippet to load an [enviornment module](https://modules.readthedocs.io/en/latest/)
+if required on your system:
+
+```yaml
+before_script: "module load quarto/1.4.549"
+```
+
+## Disclaimer
+
+If you want to add disclaimer box at the top of every quarto document (for instance, to mark the report as preliminary),
+you can do so using the `dso.quarto.disclaimer` option. For instance, the following configuration...
+
+```yaml
+dso:
+    quarto:
+        disclaimer:
+            title: This is a preliminary document
+            text: |-
+                The results presented in this report have not been reviewed for correctness.
+                Please be careful when interpreting the results.
+```
+
+...would result in the following header of the document:
+
+![quarto disclaimer](../img/dso-quarto-disclaimer.png)
+
+## Watermarking
+
+DSO can automatically add watermarks to all plots in a quarto document. Again, this might be useful for
+marking figures as preliminary. The following configuration
+
+```yaml
+dso:
+    quarto:
+        watermark:
+            text: preliminary
+```
+
+... would result in a watermark as shown here:
+
+![quarto watermark](../img/dso-quarto-watermark.png)
+
+The watermark can be further customized using the following options:
+
+```yaml
+watermark:
+    text: DRAFT!!!111elf
+    tile_size: [100, 100] # in pixel. There will always be an instance of the text in the top left and bottom right corner of the tile
+    font_size: 48
+    font_color: red
+    font_outline_size: 5
+    font_outline_color: "#00FF0099"
+```
+
+On a technical level, watermarking is implemented as a [pandoc filter](https://pandoc.org/filters.html) using [panflute](https://scorreia.com/software/panflute/). After quarto created an intermediate markdown file, pandoc parses it into an abstract syntax tree (AST).
+The pandoc filter traverses the AST and manipulates each image before pandoc continues conversion into the destination format (usually HTML).
diff --git a/_static/documentation_options.js b/_static/documentation_options.js
@@ -1,5 +1,5 @@
 const DOCUMENTATION_OPTIONS = {
-    VERSION: '0.1.dev1+g8c1d840',
+    VERSION: '0.1.dev1+gadd568c',
     LANGUAGE: 'en',
     COLLAPSE_INDEX: false,
     BUILDER: 'html',

diff --git a/cli_command_reference.html b/cli_command_reference.html
@@ -53,7 +53,7 @@
   <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="_static/documentation_options.js?v=a2eea54d"></script>
+    <script src="_static/documentation_options.js?v=974b7fd0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -67,7 +67,7 @@
     <link rel="prev" title="Installation" href="cli_installation.html" />
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <meta name="docsearch:language" content="en"/>
-  <meta name="docsearch:version" content="0.1.dev1+g8c1d840" />
+  <meta name="docsearch:version" content="0.1.dev1+gadd568c" />
   </head>
 
 
@@ -159,7 +159,6 @@
 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/templates.html">Project and stage templates</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/params_files.html">Configuration files</a></li>
-<li class="toctree-l1"><a class="reference internal" href="user_guide/dvc.html">DVC integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/pre_commit.html">pre-commit integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/uv.html"><code class="docutils literal notranslate"><span class="pre">uv</span></code> integration</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="user_guide/linting.html">Linting</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>

diff --git a/cli_configuration.html b/cli_configuration.html
@@ -53,7 +53,7 @@
   <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="_static/documentation_options.js?v=a2eea54d"></script>
+    <script src="_static/documentation_options.js?v=974b7fd0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -67,7 +67,7 @@
     <link rel="prev" title="Command reference" href="cli_command_reference.html" />
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <meta name="docsearch:language" content="en"/>
-  <meta name="docsearch:version" content="0.1.dev1+g8c1d840" />
+  <meta name="docsearch:version" content="0.1.dev1+gadd568c" />
   </head>
 
 
@@ -159,7 +159,6 @@
 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/templates.html">Project and stage templates</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/params_files.html">Configuration files</a></li>
-<li class="toctree-l1"><a class="reference internal" href="user_guide/dvc.html">DVC integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/pre_commit.html">pre-commit integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/uv.html"><code class="docutils literal notranslate"><span class="pre">uv</span></code> integration</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="user_guide/linting.html">Linting</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>

diff --git a/cli_installation.html b/cli_installation.html
@@ -53,7 +53,7 @@
   <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="_static/documentation_options.js?v=a2eea54d"></script>
+    <script src="_static/documentation_options.js?v=974b7fd0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -67,7 +67,7 @@
     <link rel="prev" title="FAQ" href="faq.html" />
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <meta name="docsearch:language" content="en"/>
-  <meta name="docsearch:version" content="0.1.dev1+g8c1d840" />
+  <meta name="docsearch:version" content="0.1.dev1+gadd568c" />
   </head>
 
 
@@ -159,7 +159,6 @@
 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/templates.html">Project and stage templates</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/params_files.html">Configuration files</a></li>
-<li class="toctree-l1"><a class="reference internal" href="user_guide/dvc.html">DVC integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/pre_commit.html">pre-commit integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/uv.html"><code class="docutils literal notranslate"><span class="pre">uv</span></code> integration</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="user_guide/linting.html">Linting</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>
@@ -370,7 +369,7 @@ <h1>Installation<a class="headerlink" href="#installation" title="Link to this h
 </div>
 <p>This command installs the <code class="docutils literal notranslate"><span class="pre">dso</span></code> binary:</p>
 <div class="highlight-ansi-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>dso<span class="w"> </span>--version
-dso, version 0.1.dev1+g8c1d840
+dso, version 0.1.dev1+gadd568c
 </pre></div>
 </div>
 <p>If you prefer to manage the Python environment yourself, you can use <code class="docutils literal notranslate"><span class="pre">pip</span></code> as usual:</p>

diff --git a/contributing.html b/contributing.html
@@ -53,7 +53,7 @@
   <link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
 <link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
 
-    <script src="_static/documentation_options.js?v=a2eea54d"></script>
+    <script src="_static/documentation_options.js?v=974b7fd0"></script>
     <script src="_static/doctools.js?v=9bcbadda"></script>
     <script src="_static/sphinx_highlight.js?v=dc90522c"></script>
     <script src="_static/clipboard.min.js?v=a7894cd8"></script>
@@ -67,7 +67,7 @@
     <link rel="prev" title="Changelog" href="CHANGELOG.html" />
   <meta name="viewport" content="width=device-width, initial-scale=1"/>
   <meta name="docsearch:language" content="en"/>
-  <meta name="docsearch:version" content="0.1.dev1+g8c1d840" />
+  <meta name="docsearch:version" content="0.1.dev1+gadd568c" />
   </head>
 
 
@@ -159,7 +159,6 @@
 <li class="toctree-l1"><a class="reference internal" href="getting_started.html">Getting started</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/templates.html">Project and stage templates</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/params_files.html">Configuration files</a></li>
-<li class="toctree-l1"><a class="reference internal" href="user_guide/dvc.html">DVC integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/pre_commit.html">pre-commit integration</a></li>
 <li class="toctree-l1"><a class="reference internal" href="user_guide/uv.html"><code class="docutils literal notranslate"><span class="pre">uv</span></code> integration</a></li>
 <li class="toctree-l1 has-children"><a class="reference internal" href="user_guide/linting.html">Linting</a><details><summary><span class="toctree-toggle" role="presentation"><i class="fa-solid fa-chevron-down"></i></span></summary><ul>