diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml new file mode 100644 index 00000000..10014b77 --- /dev/null +++ b/.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 diff --git a/.github/workflows/release.yaml b/.github/workflows/release.yaml index 2447ddd9..235cf860 100644 --- a/.github/workflows/release.yaml +++ b/.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 diff --git a/docs/docs/reference/filetypes.md b/docs/docs/reference/filetypes.md index 166e253c..9e114bd4 100644 --- a/docs/docs/reference/filetypes.md +++ b/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 diff --git a/docs/docs/reference/inputs.md b/docs/docs/reference/inputs.md index a5aeba45..c6f6ab4f 100644 --- a/docs/docs/reference/inputs.md +++ b/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 diff --git a/docs/docs/reference/metamist.md b/docs/docs/reference/metamist.md index fdf5ceab..7d8febda 100644 --- a/docs/docs/reference/metamist.md +++ b/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 diff --git a/docs/docs/reference/pedigree_info.md b/docs/docs/reference/pedigree_info.md deleted file mode 100644 index 5b7ce6c2..00000000 --- a/docs/docs/reference/pedigree_info.md +++ /dev/null @@ -1,9 +0,0 @@ -# `PedigreeInfo` class - -You can import this class directly from the `cpg_flow` package: - -```python -from cpg_flow.targets import PedigreeInfo -``` - -::: cpg_flow.targets.PedigreeInfo diff --git a/docs/docs/reference/resources.md b/docs/docs/reference/resources.md index d60c9ef8..8c66242d 100644 --- a/docs/docs/reference/resources.md +++ b/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 diff --git a/docs/docs/reference/stage.md b/docs/docs/reference/stage.md index 47b39492..7857a806 100644 --- a/docs/docs/reference/stage.md +++ b/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 diff --git a/docs/docs/reference/status.md b/docs/docs/reference/status.md index 0354faca..69042f69 100644 --- a/docs/docs/reference/status.md +++ b/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 diff --git a/docs/docs/reference/targets.md b/docs/docs/reference/targets.md index aa06246a..61762d8a 100644 --- a/docs/docs/reference/targets.md +++ b/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 diff --git a/docs/docs/reference/utils.md b/docs/docs/reference/utils.md index e6e952db..255f34db 100644 --- a/docs/docs/reference/utils.md +++ b/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 diff --git a/docs/docs/reference/workflows.md b/docs/docs/reference/workflows.md index 34d96c76..b5ff8e05 100644 --- a/docs/docs/reference/workflows.md +++ b/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 diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml index c79b6280..be55dc0d 100644 --- a/docs/mkdocs.yml +++ b/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