Scaffold Material documentation site and update guides#70
Open
EvickaStudio wants to merge 5 commits intodevfrom
Open
Scaffold Material documentation site and update guides#70EvickaStudio wants to merge 5 commits intodevfrom
EvickaStudio wants to merge 5 commits intodevfrom
Conversation
Contributor
Reviewer's GuideScaffolds a MkDocs Material documentation site (mkdocs.yml, themed assets, navigation structure) and rewrites key docs into a task/area-structured hierarchy with code-accurate workflows, while updating dev dependencies (mkdocs-material, regex) and refreshing lockfiles/requirements for consistency. Flow diagram for MkDocs Material documentation structuregraph TD
Home[index_md]:::page
TutorialsIndex[tutorials_index_md]:::page
FirstNotification[tutorials_first_notification_md]:::page
HowToIndex[how_to_index_md]:::page
SetupDevEnv[how_to_setup_dev_environment_md]:::page
ConfigureWebUI[how_to_configure_web_ui_md]:::page
AddCustomProvider[how_to_add_custom_provider_md]:::page
PrepareCommit[how_to_prepare_commit_md]:::page
ReferenceIndex[reference_index_md]:::page
ConfigRef[reference_configuration_md]:::page
CLIRef[reference_cli_md]:::page
MakeTargetsRef[reference_make_targets_md]:::page
ExplanationIndex[explanation_index_md]:::page
ArchitecturePage[explanation_architecture_md]:::page
SecurityPage[explanation_security_md]:::page
Home --> TutorialsIndex
Home --> HowToIndex
Home --> ReferenceIndex
Home --> ExplanationIndex
TutorialsIndex --> FirstNotification
HowToIndex --> SetupDevEnv
HowToIndex --> ConfigureWebUI
HowToIndex --> AddCustomProvider
HowToIndex --> PrepareCommit
ReferenceIndex --> ConfigRef
ReferenceIndex --> CLIRef
ReferenceIndex --> MakeTargetsRef
ExplanationIndex --> ArchitecturePage
ExplanationIndex --> SecurityPage
classDef page fill:#ffe0b2,stroke:#e65100,stroke-width:1.5px,border-radius:6px;
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Hey - I've found 2 issues, and left some high level feedback:
- You’ve added
mkdocs-materialonly to thedevextra inpyproject.toml; consider also adding it torequirements-dev.txt(or regenerating that file) so non-uvworkflows that rely onpip install -r requirements-dev.txtcan build the docs site consistently. - The
edit_uri: edit/dev/docs/inmkdocs.ymlhardcodes thedevbranch; if your default or primary docs branch is different (e.g.main), you may want to align this path so the "Edit on GitHub" links point to the branch you actually expect contributors to work against.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- You’ve added `mkdocs-material` only to the `dev` extra in `pyproject.toml`; consider also adding it to `requirements-dev.txt` (or regenerating that file) so non-`uv` workflows that rely on `pip install -r requirements-dev.txt` can build the docs site consistently.
- The `edit_uri: edit/dev/docs/` in `mkdocs.yml` hardcodes the `dev` branch; if your default or primary docs branch is different (e.g. `main`), you may want to align this path so the "Edit on GitHub" links point to the branch you actually expect contributors to work against.
## Individual Comments
### Comment 1
<location> `mkdocs.yml:90-91` </location>
<code_context>
+ - pymdownx.caret
+ - pymdownx.tilde
+ - pymdownx.critic
+ - pymdownx.arithmatex:
+ generic: true
+
+extra_css:
</code_context>
<issue_to_address>
**issue (bug_risk):** Math rendering may not work without including a math JS library alongside `pymdownx.arithmatex`.
This extension only wraps math in spans; you still need a renderer (e.g., MathJax or KaTeX) loaded via `extra_javascript` or the theme for formulas to display. If you use LaTeX-style math, add the appropriate JS include; if you don’t, consider removing this extension to keep the config simpler.
</issue_to_address>
### Comment 2
<location> `docs/reference/configuration.md:89-91` </location>
<code_context>
+
+## Runtime/state/session variables
+
+These are read directly from environment (outside the `MOODLEMATE_` nested model in two cases):
+
+- `MOODLEMATE_SESSION_ENCRYPTION_KEY` (optional): enables encrypted Moodle session cache.
+- `MOODLE_SESSION_FILE` (default `moodle_session.json`): path for encrypted session cache file.
+- `MOODLE_STATE_FILE` (optional): explicit path for state file.
+- `MOODLE_STATE_DIR` (optional): directory for `state.json`.
+
+If neither `MOODLE_STATE_FILE` nor `MOODLE_STATE_DIR` is set and `/app/state` does not exist, fallback is local `./state.json`.
-These are read directly from the environment:
</code_context>
<issue_to_address>
**issue (typo):** Clarify environment-variable description and fix the "two cases" mismatch.
The text says variables are read "from environment" and mentions the `MOODLEMATE_` nested model "in two cases", but then lists four variables. Please fix the grammar (add "the") and either remove the "two cases" wording or make it accurately reflect the subset you intend to highlight.
```suggestion
## Runtime/state/session variables
These are read directly from the environment (outside the `MOODLEMATE_` nested model):
```
</issue_to_address>Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
Comment on lines
+90
to
+91
| - pymdownx.arithmatex: | ||
| generic: true |
Contributor
There was a problem hiding this comment.
issue (bug_risk): Math rendering may not work without including a math JS library alongside pymdownx.arithmatex.
This extension only wraps math in spans; you still need a renderer (e.g., MathJax or KaTeX) loaded via extra_javascript or the theme for formulas to display. If you use LaTeX-style math, add the appropriate JS include; if you don’t, consider removing this extension to keep the config simpler.
Comment on lines
+89
to
+91
| ## Runtime/state/session variables | ||
|
|
||
| These are read directly from environment (outside the `MOODLEMATE_` nested model in two cases): |
Contributor
There was a problem hiding this comment.
issue (typo): Clarify environment-variable description and fix the "two cases" mismatch.
The text says variables are read "from environment" and mentions the MOODLEMATE_ nested model "in two cases", but then lists four variables. Please fix the grammar (add "the") and either remove the "two cases" wording or make it accurately reflect the subset you intend to highlight.
Suggested change
| ## Runtime/state/session variables | |
| These are read directly from environment (outside the `MOODLEMATE_` nested model in two cases): | |
| ## Runtime/state/session variables | |
| These are read directly from the environment (outside the `MOODLEMATE_` nested model): |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Create a Material documentation site with structured navigation and rewrite guides to include code-verified workflows. Update dependencies to include mkdocs-material for improved documentation styling. Refresh lockfiles for consistency.
Summary by Sourcery
Scaffold a MkDocs Material documentation site with structured navigation and improved theming, expand and reorganize user-facing docs into tutorials, how-to guides, reference, and explanations, and refresh tooling to support the new docs stack.
Enhancements:
Documentation:
Note
Low Risk
Docs-only changes plus dev-only dependency/lockfile updates; low runtime risk, with minor risk of doc build/config issues due to new MkDocs Material setup.
Overview
Adds a full MkDocs Material documentation site (
mkdocs.yml) with new landing page and sectioned navigation for Tutorials, How-to, Reference, and Explanation, plus custom theme styling indocs/stylesheets/extra.css.Rewrites/expands guides and references to be more workflow-accurate (Web UI security notes, provider auto-discovery/how to add a provider, dev setup/commit checklist, CLI/config reference), and updates dev dependencies to include
mkdocs-material(refreshingrequirements*anduv.lock).Written by Cursor Bugbot for commit f5cc775. This will update automatically on new commits. Configure here.