Add documentation pages #4
Conversation
- remove `_config.yml` file
- update copyright year to 2025 - simplify the license text to the standard GPLv3 preamble and conditions - remove the full text of the GPLv3, directing users to gnu.org for the full license
- bump version to 2.0.0 - update description and readme reference - add development dependencies for documentation generation - integrate mkdocs for comprehensive project documentation - include basic structure, installation guide, and usage examples - configure material theme for enhanced readability and navigation - add a license file - add a logo and favicon - configure the css and javascript files
- add workflow file to automatically deploy mkdocs documentation to github pages - configure workflow to trigger on push to main, manual dispatch, and pull requests to main
|
Caution Review failedThe pull request is closed. WalkthroughThis update introduces a new documentation system using MkDocs, adds comprehensive user and example documentation, and customizes site styling and math rendering. The project license is restructured, and the version is updated to 2.0.0 with new development dependencies. The previous Jekyll configuration and full license text are replaced or relocated. Changes
Sequence Diagram(s)sequenceDiagram
actor User
participant GitHub
participant Workflow
participant MkDocs
participant GitHubPages
User->>GitHub: Push to main / PR / Manual dispatch
GitHub->>Workflow: Trigger deploy.yml
Workflow->>Workflow: Checkout code, setup Python, install MkDocs
Workflow->>MkDocs: Build and deploy documentation (mkdocs gh-deploy)
MkDocs->>GitHubPages: Publish site
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (1)
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. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. 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: 2
🧹 Nitpick comments (10)
docs/extra.css (1)
5-7: Consider accessibility implications of black background override.The black background override using
!importantmay impact readability and accessibility. Consider:
- Testing contrast ratios with text colors
- Whether the override is necessary or could be achieved through theme configuration
- Impact on users with visual impairments
Consider testing the color contrast or using a slightly lighter background color for better accessibility:
- --md-default-bg-color: #000 !important; + --md-default-bg-color: #111 !important;.github/workflows/deploy.yml (1)
27-30: Sync pipeline dependencies withpyproject.tomldev group.
The workflow installspymdown-extensions, but this plugin isn’t listed in your development dependencies. Consider adding it to thedevgroup inpyproject.tomlto keep CI and local setups aligned.docs/test-example.md (1)
29-33: Specify languages for all fenced code blocks.
Several output blocks lack a language identifier, which hurts syntax highlighting. For example:- ``` + ```textRepeat for each output fence at lines 29–33, 85–91, 104–109, 119–122, 135–139, and 149–153.
Also applies to: 85-91, 104-109, 119-122, 135-139, 149-153
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
29-29: Fenced code blocks should have a language specified
null(MD040, fenced-code-language)
docs/index.md (5)
22-23: Unify unordered list markers.
You mix*and-for bullets. Markdownlint (MD004) recommends a single style—prefer using*consistently:- - [Usage](./usage.md) + * [Usage](./usage.md)🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
22-22: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
35-36: Remove blank line inside blockquote.
Blank lines in blockquotes can interrupt styling in some renderers. Merge lines 35–36:> 🛑 **Note:** This package was developed for Unix-based systems. Windows support is not guaranteed.🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
36-36: Blank line inside blockquote
null(MD028, no-blanks-blockquote)
37-37: Adjust phrasing for countable nouns.
“large amount of binaries available” → “large number of binaries available” for grammatical correctness.🧰 Tools
🪛 LanguageTool
[uncategorized] ~37-~37: ‘Amount of’ should usually only be used with uncountable or mass nouns. Consider using “number” if this is not the case.
Context: ...esigned to usecondadue to the large amount of binaries available. ### Steps 1. C...(AMOUNTOF_TO_NUMBEROF)
48-56: Use consistent bullet style in nested lists.
Nested items under step 2 use-, but top-level uses*. Align on*:- - MPSolve - - chealpix + * MPSolve + * chealpixAnd similarly for the subsequent parameter bullets.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
48-48: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
49-49: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
52-52: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
53-53: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
54-54: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
55-55: Unordered list style
Expected: asterisk; Actual: dash(MD004, ul-style)
62-62: Clarify the verb form in step 4.
“Or changing the parameters online” is awkward. Consider:Or change the parameters on the command line without editing
config.mk.🧰 Tools
🪛 LanguageTool
[uncategorized] ~62-~62: This verb may not be in the correct form. Consider using a different form for this context.
Context: ...bash make installOr changing the parameters online (no need to rewri...(AI_EN_LECTOR_REPLACEMENT_VERB_FORM)
docs/usage.md (2)
9-17: Add installation instructions to the Setup section.Right now the guide shows imports but doesn’t tell users how to install the package (and its dependencies). Consider adding a brief “Installation” subsection under Setup, for example:
### Installation ```bash pip install polymv healpyThis will help users get started without jumping to other parts of the docs. --- `34-36`: **Specify a language for output fences to satisfy markdownlint (MD040).** All the output blocks (e.g., shapes and arrays) currently start with plain ``````` and trigger MD040. Please add a language identifier like `text` or `console` at each opening fence. For example: ```diff - ``` + ```text (1127251, 2)Apply the same pattern for the other output blocks at lines 50–52, 61–64, 79–86, 100–104, 118–120, 134–136, and 145–148. Also applies to: 50-52, 61-64, 79-86, 100-104, 118-120, 134-136, 145-148 <details> <summary>🧰 Tools</summary> <details> <summary>🪛 markdownlint-cli2 (0.17.2)</summary> 34-34: Fenced code blocks should have a language specified null (MD040, fenced-code-language) </details> </details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used: CodeRabbit UI** **Review profile: CHILL** **Plan: Pro** <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between f8ec14412740f97efb7331dabd43614424f92fec and fe173ebb5631fbb7ee04d47187042e42d07600e1. </details> <details> <summary>⛔ Files ignored due to path filters (3)</summary> * `docs/favicon.ico` is excluded by `!**/*.ico` * `docs/logo.png` is excluded by `!**/*.png` * `uv.lock` is excluded by `!**/*.lock` </details> <details> <summary>📒 Files selected for processing (11)</summary> * `.github/workflows/deploy.yml` (1 hunks) * `LICENSE` (1 hunks) * `_config.yml` (0 hunks) * `docs/LICENSE.md` (1 hunks) * `docs/extra.css` (1 hunks) * `docs/index.md` (1 hunks) * `docs/javascripts/mathjax.js` (1 hunks) * `docs/test-example.md` (1 hunks) * `docs/usage.md` (1 hunks) * `mkdocs.yml` (1 hunks) * `pyproject.toml` (2 hunks) </details> <details> <summary>💤 Files with no reviewable changes (1)</summary> * _config.yml </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 markdownlint-cli2 (0.17.2)</summary> <details> <summary>docs/test-example.md</summary> 29-29: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 86-86: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 104-104: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 119-119: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 135-135: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 150-150: Fenced code blocks should have a language specified null (MD040, fenced-code-language) </details> <details> <summary>docs/index.md</summary> 22-22: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 36-36: Blank line inside blockquote null (MD028, no-blanks-blockquote) --- 48-48: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 49-49: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 52-52: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 53-53: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 54-54: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 55-55: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 79-79: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 80-80: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) --- 81-81: Unordered list style Expected: asterisk; Actual: dash (MD004, ul-style) </details> <details> <summary>docs/usage.md</summary> 34-34: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 50-50: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 61-61: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 79-79: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 100-100: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 118-118: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 134-134: Fenced code blocks should have a language specified null (MD040, fenced-code-language) --- 145-145: Fenced code blocks should have a language specified null (MD040, fenced-code-language) </details> </details> <details> <summary>🪛 LanguageTool</summary> <details> <summary>docs/index.md</summary> [uncategorized] ~37-~37: ‘Amount of’ should usually only be used with uncountable or mass nouns. Consider using “number” if this is not the case. Context: ...esigned to use `conda` due to the large amount of binaries available. ### Steps 1. C... (AMOUNTOF_TO_NUMBEROF) --- [uncategorized] ~62-~62: This verb may not be in the correct form. Consider using a different form for this context. Context: ... ```bash make install ``` Or changing the parameters online (no need to rewri... (AI_EN_LECTOR_REPLACEMENT_VERB_FORM) </details> </details> </details> <details> <summary>🔇 Additional comments (7)</summary><blockquote> <details> <summary>docs/javascripts/mathjax.js (2)</summary> `1-12`: **LGTM! Standard MathJax configuration.** The MathJax configuration is well-structured and follows standard practices: - Proper delimiter configuration for inline `\(...\)` and display `\[...\]` math - Escape and environment processing enabled appropriately - HTML class filtering configured to only process `arithmatex` classes --- `14-19`: <details> <summary>❓ Verification inconclusive</summary> **Verify document$ observable source and consider error handling.** The document subscription logic appears to be for MkDocs Material theme integration, but there are a few considerations: 1. Ensure `document$` observable is properly available in the context where this script runs 2. Consider adding error handling for MathJax operations --- 🏁 Script executed: ```shell #!/bin/bash # Verify if document$ is used consistently in MkDocs Material setups rg -A 3 -B 3 "document\$" --type jsLength of output: 36
🏁 Script executed:
#!/bin/bash # Inspect docs/javascripts/mathjax.js for imports or definitions of document$ rg "^import" -n docs/javascripts/mathjax.js rg "document\$" -n docs/javascripts/mathjax.js # Show the top of the file to see how document$ is introduced sed -n '1,200p' docs/javascripts/mathjax.jsLength of output: 521
Confirm
document$availability and add MathJax error handlingIt looks like
document$isn’t defined or imported in docs/javascripts/mathjax.js, so you’ll need to ensure the MkDocs Material theme actually provides it at runtime. It’s also safer to catch any MathJax errors rather than letting them fail silently.• Verify that the MkDocs Material theme (and version) you’re using exports a global
document$observable before this script runs.
• Guard against missingdocument$to avoid runtime exceptions:if (typeof document$ !== 'undefined' && document$.subscribe) { document$.subscribe({ next: () => { MathJax.startup.output.clearCache(); MathJax.typesetClear(); MathJax.texReset(); MathJax.typesetPromise(); }, error: err => console.error('MathJax update error:', err), }); } else { console.warn('`document$` is not available—MathJax hook skipped'); }• Consider logging or reporting any MathJax errors so you can diagnose issues in the wild.
docs/extra.css (1)
1-3: LGTM! Clean CSS variable definition.
The CSS custom property definition for the primary color is well-structured and follows Material theme conventions.
docs/LICENSE.md (1)
1-14: Inconsistency with AI summary - clarify purpose of this license file.
The AI summary indicates this file should contain "the full GNU General Public License (GPL) version 3 or later text" and "provides the full detailed license text for documentation purposes." However, this file contains the same minimal copyright notice as the root LICENSE file, not the full GPL v3 text.
Please clarify:
- Should this file contain the complete GPL v3 license text?
- Or is this intended to be a duplicate of the root LICENSE for documentation purposes?
If the intent is to include the full GPL v3 text here, you can obtain it from:
What is the complete text of the GNU General Public License version 3?
Likely an incorrect or invalid review comment.
pyproject.toml (1)
11-11: Version bump looks good; ensure consistency across docs and deployment.
The project version has been updated to 2.0.0. Please verify that this new version is reflected correctly in your documentation, release notes, and on PyPI (if you plan to publish).
mkdocs.yml (1)
1-96: MkDocs configuration looks solid.
The navigation, theme settings, plugins, and Markdown extensions are all well-structured and align with your documentation goals.
docs/usage.md (1)
1-149: Overall: usage guide is clear and thorough.
Great job walking users through generating synthetic data, computing multipole vectors, using utility functions, and calculating Fréchet mean vectors with example outputs. The structure aligns well with the MkDocs framework and complements the rest of the documentation.
🧰 Tools
🪛 markdownlint-cli2 (0.17.2)
34-34: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
50-50: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
61-61: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
79-79: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
100-100: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
118-118: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
134-134: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
145-145: Fenced code blocks should have a language specified
null
(MD040, fenced-code-language)
- remove pull request trigger to avoid duplicate deployments
Summary by CodeRabbit
New Features
Chores
Style
Documentation