add details about how docs are build #479
Conversation
WalkthroughThe README.md file was significantly expanded and restructured, transforming it from a brief overview into a comprehensive documentation guide. The update introduces detailed sections on documentation architecture, build instructions, CI/CD workflows, development guidelines, troubleshooting, and contribution processes, replacing the previous minimal content. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~8 minutes Poem
Note ⚡️ Unit Test Generation is now available in beta!Learn more here, or try it out under "Finishing Touches" below. ✨ Finishing Touches🧪 Generate unit tests
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. 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (2)
README.md (2)
35-54: Specify language for fenced repo-tree blockThe ASCII tree is inside a code fence without a language tag, triggering MD040.
Addtext(ornone) after the opening back-ticks to silence the linter and improve syntax-highlighting consistency.-``` +```text pyopenms-docs/ ├── .github/workflows/ # CI/CD pipelines … └── postBuild # Binder post-installation script -``` +```
296-299: Replace bare URLs with Markdown linksBare URLs at Binder and “Getting Help” sections violate MD034 and reduce readability. Wrap them in standard Markdown link syntax.
-- Latest: https://mybinder.org/v2/gh/OpenMS/pyopenms-docs/master+ipynb -- Specific branch: Replace `master+ipynb` with branch name +- **Latest Binder**: [Launch](https://mybinder.org/v2/gh/OpenMS/pyopenms-docs/master+ipynb) +- **Specific branch**: replace `master+ipynb` in the URL with the desired branch. -**Issues**: https://github.com/OpenMS/pyopenms-docs/issues -**Discord**: https://discord.com/invite/4TAGhqJ7s5 -**Documentation**: https://pyopenms.readthedocs.io/ +**Issues**: <https://github.com/OpenMS/pyopenms-docs/issues> +**Discord**: <https://discord.com/invite/4TAGhqJ7s5> +**Documentation**: <https://pyopenms.readthedocs.io/>Also applies to: 340-342
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
14-14: Link fragments should be valid
(MD051, link-fragments)
36-36: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
297-297: Bare URL used
(MD034, no-bare-urls)
340-340: Bare URL used
(MD034, no-bare-urls)
341-341: Bare URL used
(MD034, no-bare-urls)
342-342: Bare URL used
(MD034, no-bare-urls)
🔇 Additional comments (1)
README.md (1)
355-357: Verify licence filenameThe link points to
License.txt, but many repositories useLICENSEorLICENSE.txt. Please confirm the exact filename to avoid a 404.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (4)
README.md (4)
12-21: Keep the Table of Contents in sync with the document
Dependencies,Contributing, andLicenseare top-level sections (Lines 299, 343, 354) but are missing from the TOC (Lines 14-21). This creates broken in-page links if someone adds them later with an anchor generator and can confuse readers who skim the TOC for those topics.
Consider regenerating the TOC automatically (e.g. withdoctocormarkdown-toc) or manually adding the missing entries.
34-36: Add a language hint to the fenced code block
markdownlintflags MD040 because the tree listing fence lacks a language.
A simple “text” spec keeps syntax highlighters neutral while silencing the linter.-``` +```text
295-296: Wrap the bare Binder URL in Markdown link syntaxMD034 warns about bare links. Wrapping the URL improves readability and passes linters.
- - Latest: https://mybinder.org/v2/gh/OpenMS/pyopenms-docs/master+ipynb + - Latest: [Binder ‑ latest](https://mybinder.org/v2/gh/OpenMS/pyopenms-docs/master+ipynb)
339-341: Convert bare reference links to proper Markdown linksReplace the three bare URLs with explicit link syntax to satisfy MD034:
- - **Issues**: https://github.com/OpenMS/pyopenms-docs/issues - - **Discord**: https://discord.com/invite/4TAGhqJ7s5 - - **Documentation**: https://pyopenms.readthedocs.io/ + - **Issues**: <https://github.com/OpenMS/pyopenms-docs/issues> + - **Discord**: <https://discord.com/invite/4TAGhqJ7s5> + - **Documentation**: <https://pyopenms.readthedocs.io/>
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
README.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.17.2)
README.md
35-35: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
296-296: Bare URL used
(MD034, no-bare-urls)
339-339: Bare URL used
(MD034, no-bare-urls)
340-340: Bare URL used
(MD034, no-bare-urls)
341-341: Bare URL used
(MD034, no-bare-urls)
⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)
- GitHub Check: build-test
🔇 Additional comments (1)
README.md (1)
5-11: Nice improvement – broken Installation anchor resolvedThe earlier review flagged a missing
Installationsection.
That link has been removed from the TOC, eliminating the MD051 violation.
Summary by CodeRabbit