Auto-render reference docs from modules, add strict PR check

.github/workflows/docs.yaml

@@ -0,0 +1,36 @@
+name: Docs
+
+on:
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'src/cpg_flow/**'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/docs.yaml'
+
+permissions: {}
+
+jobs:
+  strict-build:
+    name: mkdocs build --strict
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        shell: bash -leo pipefail {0}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
+        with:
+          persist-credentials: false
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@37802adc94f370d6bfd71619e3f0bf239e1f3b78 #v7.6.0
+        with:
+          enable-cache: false
+
+      - name: Install project dependencies
+        run: uv sync
+
+      - name: Build docs strictly
+        run: uv run mkdocs build -f docs/mkdocs.yml --strict --clean

.github/workflows/release.yaml

@@ -71,7 +71,7 @@ jobs:
       contents: read
     defaults:
       run:
-        shell: bash -l {0}
+        shell: bash -leo pipefail {0}
     env:
       DOCKER_BUILDKIT: 1
       BUILDKIT_PROGRESS: plain
@@ -117,7 +117,7 @@ jobs:
       id-token: write
     defaults:
       run:
-        shell: bash -l {0}
+        shell: bash -leo pipefail {0}
     steps:
       - name: Checkout
         uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd #v6.0.2
@@ -146,7 +146,7 @@ jobs:
       contents: write
     defaults:
       run:
-        shell: bash -l {0}
+        shell: bash -leo pipefail {0}
     steps:
       # Persisted credentials are required so `mike deploy --push` can push to
       # gh-pages. This job uploads no artifacts, so the token cannot leak via

docs/docs/reference/filetypes.md

@@ -1,31 +1,3 @@
 # Filetypes
 
-The following filetypes are available to use:
-
-- `AlignmentInput`
-- `CramOrBamPath`
-- `BamPath`
-- `CramPath`
-- `GvcfPath`
-- `FastqPair`
-- `FastqPairs`
-
-You can import them from the `cpg_flow` package:
-
-```python
-from cpg_flow import AlignmentInput, CramOrBamPath, BamPath, CramPath, GvcfPath, FastqPair, FastqPairs
-```
-
-::: cpg_flow.filetypes.AlignmentInput
-
-::: cpg_flow.filetypes.CramOrBamPath
-
-::: cpg_flow.filetypes.BamPath
-
-::: cpg_flow.filetypes.CramPath
-
-::: cpg_flow.filetypes.GvcfPath
-
-::: cpg_flow.filetypes.FastqPair
-
-::: cpg_flow.filetypes.FastqPairs
+::: cpg_flow.filetypes

docs/docs/reference/inputs.md

@@ -1,15 +1,3 @@
 # Inputs
 
-There are Metamist wrappers built to get input sequencing groups.
-
-You can import these from the `cpg_flow` package:
-
-```python
-from cpg_flow.inputs import add_sg_to_dataset, get_multicohort, create_multicohort
-```
-
-::: cpg_flow.inputs.add_sg_to_dataset
-
-::: cpg_flow.inputs.get_multicohort
-
-::: cpg_flow.inputs.create_multicohort
+::: cpg_flow.inputs

docs/docs/reference/metamist.md

@@ -1,19 +1,3 @@
 # Metamist
 
-Helpers to communicate with the `metamist` database.
-
-::: cpg_flow.metamist.get_metamist
-
-::: cpg_flow.metamist.Metamist
-
-::: cpg_flow.metamist.AnalysisStatus
-
-::: cpg_flow.metamist.AnalysisType
-
-::: cpg_flow.metamist.Analysis
-
-::: cpg_flow.metamist.Assay
-
-::: cpg_flow.metamist.get_cohort_sgs
-
-::: cpg_flow.metamist.parse_reads
+::: cpg_flow.metamist

docs/docs/reference/resources.md

@@ -1,19 +1,3 @@
 # Resources
 
-The following resources are available for use:
-
-::: cpg_flow.resources.gcp_machine_name
-
-::: cpg_flow.resources.MachineType
-
-::: cpg_flow.resources.STANDARD
-
-::: cpg_flow.resources.HIGHMEM
-
-::: cpg_flow.resources.JobResource
-
-::: cpg_flow.resources.storage_for_cram_qc_job
-
-::: cpg_flow.resources.joint_calling_scatter_count
-
-::: cpg_flow.resources.storage_for_joint_vcf
+::: cpg_flow.resources

docs/docs/reference/stage.md

@@ -1,25 +1,3 @@
-# `Stage` class
+# Stage
 
-The following `Stage` classes are available to use:
-
-- `Stage`
-- `DatasetStage`
-- `CohortStage`
-- `MultiCohortStage`
-- `SequencingGroupStage`
-
-You can import them from the `cpg_flow` package:
-
-```python
-from cpg_flow.stage import Stage, DatasetStage, CohortStage, MultiCohortStage, SequencingGroupStage
-```
-
-::: cpg_flow.stage.Stage
-
-::: cpg_flow.stage.DatasetStage
-
-::: cpg_flow.stage.CohortStage
-
-::: cpg_flow.stage.MultiCohortStage
-
-::: cpg_flow.stage.SequencingGroupStage
+::: cpg_flow.stage

docs/docs/reference/status.md

@@ -1,12 +1,3 @@
 # Status
 
-Metamist wrappers to report analysis progress.
-
-
-::: cpg_flow.status.complete_analysis_job
-
-::: cpg_flow.status.StatusReporterError
-
-::: cpg_flow.status.StatusReporter
-
-::: cpg_flow.status.MetamistStatusReporter
+::: cpg_flow.status

docs/docs/reference/targets.md

@@ -1,26 +1,3 @@
-# `Target` class
+# Targets
 
-The following `Target` classes are available to use:
-
-- `Target`
-- `Cohort`
-- `Dataset`
-- `MultiCohort`
-- `SequencingGroup`
-
-
-You can import them from the `cpg_flow` package:
-
-```python
-from cpg_flow.targets import Cohort, Dataset, MultiCohort, SequencingGroup, Target
-```
-
-::: cpg_flow.targets.Target
-
-::: cpg_flow.targets.Cohort
-
-::: cpg_flow.targets.Dataset
-
-::: cpg_flow.targets.MultiCohort
-
-::: cpg_flow.targets.SequencingGroup
+::: cpg_flow.targets

docs/docs/reference/utils.md

@@ -1,39 +1,3 @@
 # Utils
 
-Utility functions and constants.
-
-::: cpg_flow.utils.format_logger
-
-::: cpg_flow.utils.chunks
-
-::: cpg_flow.utils.generator_chunks
-
-::: cpg_flow.utils.read_hail
-
-::: cpg_flow.utils.checkpoint_hail
-
-::: cpg_flow.utils.exists
-
-::: cpg_flow.utils.exists_not_cached
-
-::: cpg_flow.utils.check_exists_path
-
-::: cpg_flow.utils.get_contents_of_path
-
-::: cpg_flow.utils.can_reuse
-
-::: cpg_flow.utils.timestamp
-
-::: cpg_flow.utils.slugify
-
-::: cpg_flow.utils.rich_sequencing_group_id_seds
-
-::: cpg_flow.utils.tshirt_mt_sizing
-
-::: cpg_flow.utils.get_intervals_from_bed
-
-::: cpg_flow.utils.make_job_name
-
-::: cpg_flow.utils.hash_from_list_of_strings
-
-::: cpg_flow.utils.write_to_gcs_bucket
+::: cpg_flow.utils

docs/docs/reference/workflows.md

@@ -1,29 +1,3 @@
-# Workflow class
+# Workflow
 
-Provides a `Workflow` class and a `@stage` decorator that allow to define workflows
-in a declarative fashion.
-
-A [`Stage`](stage.md#stage-class) object is responsible for creating Hail Batch jobs and declaring outputs
-(files or metamist analysis objects) that are expected to be produced. Each stage
-acts on a [`Target`](targets.md#target-class), which can be of the following:
-
-    * SequencingGroup - an individual Sequencing Group (e.g. the CRAM of a single sample)
-    * Dataset - a stratification of SGs in this analysis by Metamist Project (e.g. all SGs in acute-care)
-    * Cohort - a stratification of SGs in this analysis by Metamist CustomCohort
-    * MultiCohort - a union of all SGs in this analysis by Metamist CustomCohort
-
-A `Workflow` object plugs stages together by resolving dependencies between different levels accordingly. Stages are
-defined in this package, and chained into Workflows by their inter-Stages dependencies. Workflow names are defined in
-main.py, which provides a way to choose a workflow using a CLI argument.
-
-::: cpg_flow.workflow.get_workflow
-
-::: cpg_flow.workflow.run_workflow
-
-::: cpg_flow.workflow.Workflow
-
-::: cpg_flow.workflow.Action
-
-::: cpg_flow.workflow.skip
-
-::: cpg_flow.workflow.path_walk
+::: cpg_flow.workflow

docs/mkdocs.yml

@@ -92,6 +92,7 @@ markdown_extensions:
   pymdownx.caret:
   pymdownx.highlight:
     line_spans: __span
+    auto_title: true
   pymdownx.inlinehilite:
   pymdownx.keys:
   pymdownx.mark:
@@ -138,7 +139,6 @@ nav:
       - reference/index.md
       - reference/stage.md
       - reference/targets.md
-      - reference/pedigree_info.md
       - reference/filetypes.md
       - reference/inputs.md
       - reference/metamist.md