Scaffold MkDocs Material docs site (GH Pages)#154
Conversation
Ports the existing GitHub-wiki pages (Home, Configuration, Output, Developer, Troubleshooting, Scripts-&-Resources) into docs/ as the seed content for the new site. Content unchanged — just relocated and renamed to URL-friendly slugs (Home -> index, Scripts-&-Resources -> resources). The wiki stays live as a fallback while the site is being established. Stack: - MkDocs Material (https://squidfunk.github.io/mkdocs-material/) - pinned in docs/requirements.txt (mkdocs==1.6.1, material==9.6.16) - mkdocs.yml configures the material theme, navigation, edit-on-github links, and pymdownx extensions (admonitions, tabbed content, superfences, etc.) CI / hosting: - .github/workflows/docs.yml runs `mkdocs build --strict` on every PR touching docs/ or mkdocs.yml (catches broken links / dead refs before merge) and additionally deploys to GitHub Pages on push to main via the modern Pages-from-Actions pattern (upload-pages-artifact + deploy-pages, no gh-pages branch). - Going with GH Pages instead of Read the Docs because we don't have org admin for the RTD account import; GH Pages keeps everything in-repo (one Settings -> Pages -> "GitHub Actions" flip is the only admin step). README updated to point at https://ylab-hi.github.io/ScanNeo2/ as primary, with the wiki as fallback. First PR against #147 — scaffold + content port only. Subsequent PRs fill the empty wiki stubs (Output sub-sections, Developer, Troubleshooting, Resources) and add link-check / per-tag-build CI. Verified locally: mkdocs build --strict produces site/ in 0.38s with no warnings.
|
Warning Review limit reached
More reviews will be available in 46 minutes and 57 seconds. Learn how PR review limits work. Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file). ⌛ How to resolve this issue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits. 🚦 How do rate limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan refill rate. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, the refill rate gradually slows as usage increases. The highest same-day bursts are limited more strictly. Please see our Fair Usage Limits Policy for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
📝 WalkthroughWalkthroughIntroduces a MkDocs-based documentation site for ScanNeo2. Six new pages cover installation, configuration blocks, pipeline output schemas, developer internals, resources, and troubleshooting. A ChangesScanNeo2 MkDocs Documentation Site
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes Possibly related issues
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (10)
docs/index.md (2)
52-52: 💤 Low valueComplete the sentence fragment.
Line 52 reads "Can be found at
.tests/integration" but lacks a subject. Per static analysis (MISSING_IT_THERE), this should be rewritten as a complete sentence, e.g., "Test data can be found at.tests/integration".✍️ Proposed fix
-Can be found at `.tests/integration` +Test data can be found at `.tests/integration`.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/index.md` at line 52, The text on line 52 is a sentence fragment that begins with a verb phrase "Can be found at `.tests/integration`" without a subject. Add an appropriate subject to the beginning of the sentence to make it grammatically complete, such as changing it to "Test data can be found at `.tests/integration`" or another suitable subject that clarifies what is being referenced.
14-14: ⚡ Quick winAdd language specifiers to fenced code blocks.
Fenced code blocks at lines 14, 22, 29, and 45 lack language identifiers (e.g.,
```bashinstead of```). This improves syntax highlighting for users and aligns with Markdown best practices (markdownlint MD040). All code blocks in this file appear to be shell/bash commands.✏️ Proposed fix
-``` +```bash mamba env create --file https://raw.githubusercontent.com/ylab-hi/ScanNeo2/main/environment.yml mamba activate scanneo2 -``` +```bash -``` +```bash mkdir -p /path/to/working/directory/ cd /path/to/working/directory/ -``` +```bash -``` +```bash git clone --recurse-submodules https://github.com/ylab-hi/ScanNeo2 -``` +```bash -``` +```bash snakemake --cores all --software-deployment-method conda -``` +```bashAlso applies to: 22-22, 29-29, 45-45
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/index.md` at line 14, The fenced code blocks in the documentation file are missing language specifiers, which prevents proper syntax highlighting and violates markdown best practices. Add the bash language identifier to all fenced code blocks that currently lack one. Specifically, update the opening fence markers for the code blocks containing mamba env create, mkdir -p /path/to/working/directory, git clone --recurse-submodules, and snakemake --cores all commands by changing the opening ``` to ```bash on lines 14, 22, 29, and 45 respectively.docs/output.md (2)
164-164: 💤 Low valueFix table formatting: add missing trailing pipe.
The table row at line 164 (
self-similarityfield) lacks a trailing pipe character, violating Markdown table syntax (markdownlint MD055). The pipe should close the row to match the format of other rows in the table.📋 Proposed fix
-| self-similarity | Float | Similarity measure between the wildtype and mutant epitope. Float values between 0 and 1. `0` Indicates no similarity or a complete difference between the WT and MT sequences. `1` Indicates perfect similarity, meaning the WT and MT sequences are identical in terms of their k-mer similarities. +| self-similarity | Float | Similarity measure between the wildtype and mutant epitope. Float values between 0 and 1. `0` Indicates no similarity or a complete difference between the WT and MT sequences. `1` Indicates perfect similarity, meaning the WT and MT sequences are identical in terms of their k-mer similarities. |🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/output.md` at line 164, The self-similarity table row in the output.md file is missing a trailing pipe character at the end, which violates Markdown table syntax. Add a pipe character `|` at the end of the self-similarity row to properly close the table row and match the formatting of other rows in the table.
5-5: ⚡ Quick winAdd language specifiers to fenced code blocks.
Three fenced code blocks (lines 5, 40, 75) lack language identifiers. Line 5 and 75 appear to be directory structure/plaintext listings; line 40 is an example output. Adding appropriate language specs (e.g.,
```textor```yaml) improves syntax highlighting and aligns with Markdown best practices.Also applies to: 40-40, 75-75
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/output.md` at line 5, Add language identifiers to the three fenced code blocks in docs/output.md that currently lack them. For the code blocks at lines 5 and 75 which contain directory structure or plaintext listings, add the text language specifier. For the code block at line 40 which contains example output, add an appropriate language specifier such as yaml or text depending on the content format. Update each opening fence marker from ``` to ```text or the relevant language identifier to improve syntax highlighting and follow Markdown best practices.docs/configuration.md (1)
8-8: ⚡ Quick winAdd YAML language specifiers to all fenced code blocks.
Nine fenced code blocks throughout the configuration documentation (lines 8, 18, 51, 64, 89, 108, 125, 144, 158, 173) lack language identifiers. All appear to be YAML examples. Adding
```yamlimproves syntax highlighting and aligns with Markdown best practices (markdownlint MD040).Also applies to: 18-18, 51-51, 64-64, 89-89, 108-108, 125-125, 144-144, 158-158, 173-173
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/configuration.md` at line 8, Multiple fenced code blocks in the configuration documentation file are missing language identifiers. Find all fenced code blocks that currently begin with just triple backticks (```) and contain YAML configuration examples, and update them to include the yaml language specifier by changing them to ```yaml. This applies to the code blocks appearing throughout the configuration document that demonstrate YAML syntax examples, improving syntax highlighting and conforming to Markdown best practices.docs/resources.md (2)
8-8: 💤 Low valueUse ISO 8601 date format for clarity.
The date "03-05-24" is ambiguous (could be March 5, 2024 or May 3, 2024 depending on locale). Consider using ISO 8601 format (YYYY-MM-DD) or spelling out the month for international clarity.
📅 Suggested format
If the date is March 5, 2024:
-MHC-I Pathogen-derived epitopes in TSV downloaded from [IEDB](https://www.immuneepitope.org/) on 03-05-24 filtered by `Epitope Length` (8-12), `Epitope Source` (Virus, Bacteria, Fungi, Archeobacterium), `MHC Restriction` (class I), `Host` (Human) and `Disease` (disease). +MHC-I Pathogen-derived epitopes in TSV downloaded from [IEDB](https://www.immuneepitope.org/) on 2024-03-05 filtered by `Epitope Length` (8-12), `Epitope Source` (Virus, Bacteria, Fungi, Archeobacterium), `MHC Restriction` (class I), `Host` (Human) and `Disease` (disease).🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/resources.md` at line 8, Replace the ambiguous date format "03-05-24" in the MHC-I Pathogen-derived epitopes description with ISO 8601 format (YYYY-MM-DD) for international clarity. Determine whether the original date represents March 5, 2024 or May 3, 2024, and replace "03-05-24" with the corresponding date in YYYY-MM-DD format (either 2024-03-05 or 2024-05-03) to eliminate locale-dependent ambiguity.
1-1: 💤 Low valueConsider broadening the title to match the filename.
The page is named
resources.mdbut the title only says "Scripts". Per the PR objectives, this ports the "Scripts-&-Resources" wiki page. Consider updating the title to "Scripts & Resources" for clarity.✏️ Suggested title update
-# Scripts +# Scripts & Resources🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/resources.md` at line 1, Update the main heading in the resources.md file from "# Scripts" to "# Scripts & Resources" to align with both the filename and the original wiki page being ported. This broader title better reflects the content scope of the document and provides clarity to readers about what the page covers..github/workflows/docs.yml (2)
21-25: 💤 Low valueConsider caching pip dependencies for faster builds.
Adding a pip cache would speed up subsequent workflow runs. This is a minor optimization since the dependencies are small.
⚡ Suggested caching
- uses: actions/setup-python@v5 with: python-version: "3.11" + cache: pip + cache-dependency-path: docs/requirements.txt - name: Install MkDocs Material🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs.yml around lines 21 - 25, Add caching for pip dependencies in the actions/setup-python step to speed up subsequent workflow runs. In the with block of the setup-python@v5 action (which currently contains python-version), add a cache parameter set to 'pip' to automatically cache the Python dependencies installed from the docs/requirements.txt file. This will cache the pip packages between workflow runs and reduce installation time.
20-20: Consider addingpersist-credentials: falseas a defense-in-depth measure.Verification confirms that
mkdocs builddoes not include the.gitdirectory in site output, and no actual credentials are leaked to the Pages artifact. However, settingpersist-credentials: falseis a security best practice to prevent accidental credential exposure if the workflow is modified in the future:Suggested change
- uses: actions/checkout@v4 + with: + persist-credentials: false🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.github/workflows/docs.yml at line 20, The actions/checkout@v4 step in the workflow does not explicitly disable credential persistence. Add `persist-credentials: false` as a parameter to the actions/checkout@v4 step to prevent accidental credential exposure as a security best practice, even though the current workflow does not leak credentials. This defensive measure ensures that if the workflow is modified in the future, credentials will not be inadvertently stored or exposed in the Pages artifact.Source: Linters/SAST tools
docs/troubleshooting.md (1)
3-3: 💤 Low valueConsider formatting the error message.
The error message would be more readable in a code block or admonition. This helps distinguish it from explanatory text when the section expands.
✨ Suggested formatting
+``` root filesystem extraction failed: extract command failed: ERROR: Failed to create user namespace: user namespace disabled +```Or as an admonition:
+!!! error "Error Message" + ``` root filesystem extraction failed: extract command failed: ERROR: Failed to create user namespace: user namespace disabled + ```🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/troubleshooting.md` at line 3, The error message starting with "root filesystem extraction failed: extract command failed: ERROR: Failed to create user namespace: user namespace disabled" is currently displayed as plain text within the troubleshooting documentation. Improve readability by wrapping this error message in a markdown code block using triple backticks (```) or by formatting it as a markdown admonition. This will visually distinguish the error message from the surrounding explanatory text and make the documentation easier to scan and understand.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/index.md`:
- Line 30: The git clone command on line 30 has two issues that need to be
fixed. First, the recurse-submodules option is missing the double-dash prefix
and should be changed from "recurse-submodules" to "--recurse-submodules" to be
valid git syntax. Second, the repository name in the URL uses lowercase
"scanneo2" but should use the correct mixed-case format "ScanNeo2" to match the
actual repository name. Update the entire clone command to include both the
correct flag syntax and the properly-cased repository name.
In `@docs/requirements.txt`:
- Around line 1-2: The mkdocs-material package version in the requirements.txt
file is outdated. Update the mkdocs-material dependency from version 9.6.16 to
version 9.7.6 or later (the latest stable version) to benefit from recent bug
fixes and security updates. Simply change the version number in the line
containing mkdocs-material to reflect the newer stable release.
In `@docs/resources.md`:
- Line 4: The heading in the resources.md file incorrectly displays the resource
path as workflow/rules/filtering/ when the actual resource path is
workflow/scripts/filtering/. Update the heading at line 4 from `##
workflow/rules/filtering/` to `## workflow/scripts/filtering/` to reflect the
correct directory structure.
In `@docs/troubleshooting.md`:
- Line 1: The first line of the troubleshooting.md file contains only a markdown
heading marker `#` with no title text, which renders as an empty heading and
breaks the navigation structure. Add the text "Troubleshooting" immediately
after the `#` symbol (with a space between them) to create a proper level 1
heading that will display correctly in the documentation and table of contents.
---
Nitpick comments:
In @.github/workflows/docs.yml:
- Around line 21-25: Add caching for pip dependencies in the
actions/setup-python step to speed up subsequent workflow runs. In the with
block of the setup-python@v5 action (which currently contains python-version),
add a cache parameter set to 'pip' to automatically cache the Python
dependencies installed from the docs/requirements.txt file. This will cache the
pip packages between workflow runs and reduce installation time.
- Line 20: The actions/checkout@v4 step in the workflow does not explicitly
disable credential persistence. Add `persist-credentials: false` as a parameter
to the actions/checkout@v4 step to prevent accidental credential exposure as a
security best practice, even though the current workflow does not leak
credentials. This defensive measure ensures that if the workflow is modified in
the future, credentials will not be inadvertently stored or exposed in the Pages
artifact.
In `@docs/configuration.md`:
- Line 8: Multiple fenced code blocks in the configuration documentation file
are missing language identifiers. Find all fenced code blocks that currently
begin with just triple backticks (```) and contain YAML configuration examples,
and update them to include the yaml language specifier by changing them to
```yaml. This applies to the code blocks appearing throughout the configuration
document that demonstrate YAML syntax examples, improving syntax highlighting
and conforming to Markdown best practices.
In `@docs/index.md`:
- Line 52: The text on line 52 is a sentence fragment that begins with a verb
phrase "Can be found at `.tests/integration`" without a subject. Add an
appropriate subject to the beginning of the sentence to make it grammatically
complete, such as changing it to "Test data can be found at
`.tests/integration`" or another suitable subject that clarifies what is being
referenced.
- Line 14: The fenced code blocks in the documentation file are missing language
specifiers, which prevents proper syntax highlighting and violates markdown best
practices. Add the bash language identifier to all fenced code blocks that
currently lack one. Specifically, update the opening fence markers for the code
blocks containing mamba env create, mkdir -p /path/to/working/directory, git
clone --recurse-submodules, and snakemake --cores all commands by changing the
opening ``` to ```bash on lines 14, 22, 29, and 45 respectively.
In `@docs/output.md`:
- Line 164: The self-similarity table row in the output.md file is missing a
trailing pipe character at the end, which violates Markdown table syntax. Add a
pipe character `|` at the end of the self-similarity row to properly close the
table row and match the formatting of other rows in the table.
- Line 5: Add language identifiers to the three fenced code blocks in
docs/output.md that currently lack them. For the code blocks at lines 5 and 75
which contain directory structure or plaintext listings, add the text language
specifier. For the code block at line 40 which contains example output, add an
appropriate language specifier such as yaml or text depending on the content
format. Update each opening fence marker from ``` to ```text or the relevant
language identifier to improve syntax highlighting and follow Markdown best
practices.
In `@docs/resources.md`:
- Line 8: Replace the ambiguous date format "03-05-24" in the MHC-I
Pathogen-derived epitopes description with ISO 8601 format (YYYY-MM-DD) for
international clarity. Determine whether the original date represents March 5,
2024 or May 3, 2024, and replace "03-05-24" with the corresponding date in
YYYY-MM-DD format (either 2024-03-05 or 2024-05-03) to eliminate
locale-dependent ambiguity.
- Line 1: Update the main heading in the resources.md file from "# Scripts" to
"# Scripts & Resources" to align with both the filename and the original wiki
page being ported. This broader title better reflects the content scope of the
document and provides clarity to readers about what the page covers.
In `@docs/troubleshooting.md`:
- Line 3: The error message starting with "root filesystem extraction failed:
extract command failed: ERROR: Failed to create user namespace: user namespace
disabled" is currently displayed as plain text within the troubleshooting
documentation. Improve readability by wrapping this error message in a markdown
code block using triple backticks (```) or by formatting it as a markdown
admonition. This will visually distinguish the error message from the
surrounding explanatory text and make the documentation easier to scan and
understand.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8c32f46e-b79a-40c9-bdf8-40520fcea0d3
📒 Files selected for processing (11)
.github/workflows/docs.yml.gitignoreREADME.mddocs/configuration.mddocs/developer.mddocs/index.mddocs/output.mddocs/requirements.txtdocs/resources.mddocs/troubleshooting.mdmkdocs.yml
- docs/index.md: 'git clone recurse-submodules https://github.com/ylab-hi/scanneo2' was missing the '--' on recurse-submodules and used the wrong-case repo URL; a user following the install guide would have hit a deploy failure. Fixed to 'git clone --recurse-submodules https://github.com/ylab-hi/ScanNeo2'. - docs/resources.md: heading said '## workflow/rules/filtering/' but the resource is actually at workflow/scripts/filtering/. Fixed. - docs/troubleshooting.md: was just a bare '#' followed by an apptainer error message. Rendered as an empty heading. Promoted to a proper H1 'Troubleshooting' + a short paragraph explaining when the apptainer/user-namespace error fires and how to avoid it (deactivate the exitron module, or enable user namespaces). - docs/requirements.txt: bumped mkdocs-material 9.6.16 -> 9.7.6 (latest stable; project is in maintenance mode upstream and pinning the current release on first setup costs us nothing). All four bugs exist in the wiki too. The wiki is becoming the fallback and will be retired in PR C of #147; fixing here on the canonical site. mkdocs build --strict remains clean.
Review summary (self-review)CI: build job green (12s, CodeRabbit commentsAll four caught real bugs — addressed inline. Summary: they're all wiki-inherited (the wiki had them too; we ported 1:1), but since this PR creates the canonical docs site, fixing on the way over is the right move. Replies in-thread point at commit What I did NOT change
Open after this PR
Awaiting deploy job's first push-to-main run to confirm https://ylab-hi.github.io/ScanNeo2/ resolves. |
1 participant
Summary
Changed
docs/seeded with the existing GitHub-wiki pages, ported 1:1 with URL-friendly slugs (Home → index,Scripts-&-Resources → resources). Content unchanged from the wiki ataa95a00(which already carries the 2026-06-17 corrections to the NMD scope andpathogen/proteincolumn names). The wiki stays live as a fallback while the new site stabilises.mkdocs.ymlat repo root: MkDocs Material theme, navigation tree, repo-link / edit-on-GitHub button, pymdownx extensions (admonition, details, superfences, tabbed, attr_list, footnotes, tables, toc with permalinks).docs/requirements.txtpinsmkdocs==1.6.1,mkdocs-material==9.6.16so the build is reproducible..github/workflows/docs.ymlhas two jobs:docs/,mkdocs.yml, or this workflow file. Usesmkdocs build --strict, which fails on broken links / dead refs. Doubles as a PR check.main. Uses the modern Pages-from-Actions pattern (actions/upload-pages-artifact+actions/deploy-pages); nogh-pagesbranch.README.mdnow points at https://ylab-hi.github.io/ScanNeo2/ as primary, with the wiki noted as fallback..gitignoreadds/site/so locally-built output doesn't leak into commits.GitHub Pages chosen over Read the Docs because the maintainer doesn't have org-admin access for the RTD account import; GH Pages keeps everything in-repo and needs only one Settings flip from an org owner.
First PR against #147 — scaffold + content port only. Follow-up PRs will fill the empty wiki stubs (alignment / pre-processing / alt-splicing / indel-SNVs sub-sections in Output; the Developer, Troubleshooting, Resources pages) and add link-check / per-tag-build (
mike) CI.For the deploy job to actually publish, an org owner needs to:
Settings → Pageson the repo.Until that flip, the build job still runs cleanly on PRs (so this PR's CI will be green), but the deploy job will fail on the first push to
main. Once Pages is enabled, the next push (or a manual workflow re-run) will deploy.QC
mkdocs build --strictsucceeds locally with no warnings (0.38s build)--strictCloses part of #147.
Summary by CodeRabbit