Okay, I should be done with this action after this. There are two related things happening with this PR:
Script to backfill docs for existing tags
The first change in this PR is to add a script that clones a pipeline, builds the documentation for each tag, previews it for you locally, and gives you the opportunity to push the changes up to GitHub.
$ ./backfill.py git@github.com:uclahs-cds/pipeline-align-DNA.git
Cloning repository into /var/folders/q5/pzb2r_1s01l6gvysk3cglxm4wpvxcb/T/tmp0967bgod ...
Generating docs for tag `v3.0.0`
Generating docs for tag `v5.0.0`
Generating docs for tag `v6.0.0`
Generating docs for tag `v6.0.1`
Generating docs for tag `v6.0.2`
Generating docs for tag `v6.1.0`
Generating docs for tag `v7.0.0`
Generating docs for tag `v7.0.1`
Generating docs for tag `v7.0.2`
Generating docs for tag `v7.0.3`
Generating docs for tag `v7.1.0`
Generating docs for tag `v7.2.0`
Generating docs for tag `v7.2.1`
Generating docs for tag `v7.3.0`
Generating docs for tag `v7.3.1`
Generating docs for tag `v8.0.0`
Generating docs for tag `v8.1.0`
Generating docs for tag `v9.0.0`
Generating docs for tag `v10.0.0-rc.1`
Updated documentation at http://localhost:8000/
Push these docs live [yes/no]? no
Not pushing docs
Stopping server...
I already ran this script for pipeline-recalibrate-BAM and pushed the changes up (https://improved-bassoon-j5jkeer.pages.github.io/release-candidate/), and in doing so discovered a few things I wanted to improve. Those fixes are the second half of this PR discussed below.
Updated repository and edit links
There are two links to GitHub on each docs page: an "Edit on GitHub" link in the upper right, and a "GitHub" link in the lower left.
The GitHub UI will show the actual tag instead of the commit it references (it's very hard to discover what tags point to a commit from the UI).
The "GitHub" link in the lower left will now link to the repository as of that tag, not the main page. The development release will still point to the main page.
Before
(I know, the hashes don't match, development and v9.0.0 aren't actually the same commit.)
After
Checklist
[x] This PR does NOT contain Protected Health Information (PHI). A repo may need to be deleted if such data is uploaded. Disclosing PHI is a major problem[^1] - Even a small leak can be costly[^2].
[x] This PR does NOT contain germline genetic data[^3], RNA-Seq, DNA methylation, microbiome or other molecular data[^4].
[x] This PR does NOT contain other non-plain text files, such as: compressed files, images (e.g..png, .jpeg), .pdf, .RData, .xlsx, .doc, .ppt, or other output files.
To automatically exclude such files using a .gitignore file, see here for example.
[x] I have set up or verified the main branch protection rule following the github standards before opening this pull request.
[x] The name of the branch is meaningful and well formatted following the standards, using [AD_username (or 5 letters of AD if AD is too long)]-[brief_description_of_branch].
[x] I have added the major changes included in this pull request to the CHANGELOG.md under the next release version or unreleased, and updated the date.
Description
Okay, I should be done with this action after this. There are two related things happening with this PR:
Script to backfill docs for existing tags
The first change in this PR is to add a script that clones a pipeline, builds the documentation for each tag, previews it for you locally, and gives you the opportunity to push the changes up to GitHub.
I already ran this script for pipeline-recalibrate-BAM and pushed the changes up (https://improved-bassoon-j5jkeer.pages.github.io/release-candidate/), and in doing so discovered a few things I wanted to improve. Those fixes are the second half of this PR discussed below.
Updated repository and edit links
There are two links to GitHub on each docs page: an "Edit on GitHub" link in the upper right, and a "GitHub" link in the lower left.
Currently the "Edit on GitHub" link always refers to the version's commit hash, like https://github.com/uclahs-cds/pipeline-align-DNA/blob/023fdba7e1a875e6893e40d5fc7609c51ef12118/README.md. The "GitHub" link always points to the main page, like https://github.com/uclahs-cds/pipeline-align-DNA.
This change makes it so that tagged versions have better contextual links, like https://github.com/uclahs-cds/pipeline-align-DNA/blob/v9.0.0/README.md and https://github.com/uclahs-cds/pipeline-align-DNA/tree/v9.0.0. The two advantages there are:
developmentrelease will still point to the main page.Before
(I know, the hashes don't match,
developmentandv9.0.0aren't actually the same commit.)After
Checklist
[x] This PR does NOT contain Protected Health Information (PHI). A repo may need to be deleted if such data is uploaded.
Disclosing PHI is a major problem[^1] - Even a small leak can be costly[^2].
[x] This PR does NOT contain germline genetic data[^3], RNA-Seq, DNA methylation, microbiome or other molecular data[^4].
[^1]: UCLA Health reaches $7.5m settlement over 2015 breach of 4.5m patient records [^2]: The average healthcare data breach costs $2.2 million, despite the majority of breaches releasing fewer than 500 records. [^3]: Genetic information is considered PHI. Forensic assays can identify patients with as few as 21 SNPs [^4]: RNA-Seq, DNA methylation, microbiome, or other molecular data can be used to predict genotypes (PHI) and reveal a patient's identity.
.png, .jpeg),.pdf,.RData,.xlsx,.doc,.ppt, or other output files.To automatically exclude such files using a .gitignore file, see here for example.
[x] I have read the code review guidelines and the code review best practice on GitHub check-list.
[x] I have set up or verified the
mainbranch protection rule following the github standards before opening this pull request.[x] The name of the branch is meaningful and well formatted following the standards, using [AD_username (or 5 letters of AD if AD is too long)]-[brief_description_of_branch].
[x] I have added the major changes included in this pull request to the
CHANGELOG.mdunder the next release version or unreleased, and updated the date.