Add MkDocs documentation #2361
Add MkDocs documentation #2361
Conversation
|
|
WalkthroughAdds a documentation site: new MkDocs config and multiple docs pages, moves API headings to lower levels, and updates Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~10 minutes
Poem
Pre-merge checks❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
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 |
|
Looks like some merge didn't go 100% as it should as there are commits in here that don't belong |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (1)
docs/index.md (1)
12-13: Fix grammar and word choice.Line 12: Replace "In order to" with "To" for conciseness. Line 13: Use hyphen for compound adjective: "community-run wiki" (not "community run wiki").
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
⛔ Files ignored due to path filters (2)
docs/res/github_fork.pngis excluded by!**/*.pngdocs/res/sample.pngis excluded by!**/*.png
📒 Files selected for processing (7)
.gitignore(1 hunks)docs/API.md(3 hunks)docs/client.md(1 hunks)docs/develop.md(1 hunks)docs/getting_started.md(1 hunks)docs/index.md(1 hunks)mkdocs.yml(1 hunks)
🧰 Additional context used
🪛 GitHub Actions: 🧪 CI
mkdocs.yml
[warning] 1-1: Prettier formatting issues found. Run 'npx prettier --write mkdocs.yml' to fix.
docs/index.md
[warning] 1-1: Prettier formatting issues found. Run 'npx prettier --write docs/index.md' to fix.
docs/getting_started.md
[warning] 1-1: Prettier formatting issues found. Run 'npx prettier --write docs/getting_started.md' to fix.
docs/client.md
[warning] 1-1: Prettier formatting issues found. Run 'npx prettier --write docs/client.md' to fix.
docs/develop.md
[warning] 1-1: Prettier formatting issues found. Run 'npx prettier --write docs/develop.md' to fix.
🪛 LanguageTool
docs/index.md
[style] ~12-~12: Consider a more concise word here.
Context: ... Starting Guide! In order to learn about game mechanics, check out t...
(IN_ORDER_TO_PREMIUM)
[grammar] ~13-~13: Use a hyphen to join words.
Context: ...game mechanics, check out the [community run wiki](https://openfront.miraheze.org...
(QB_NEW_EN_HYPHEN)
docs/getting_started.md
[style] ~24-~24: Consider using a synonym to be more concise.
Context: ...much larger chance that it will require a lot of changes, or be straight up rejected. T...
(A_LOT_OF)
[grammar] ~28-~28: Ensure spelling is correct
Context: ...e issues page. Make sure to fill it out throughly. You can then ask to be assigned in the...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
[uncategorized] ~38-~38: The official name of this software platform is spelled with a capital “H”.
Context: ... learning how to use it. ### Setup In github, fork [the repo](https://github.com/ope...
(GITHUB)
[locale-violation] ~138-~138: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ... changes are sensible, implement them. Afterwards, if your PR is set as ready to be revie...
(AFTERWARDS_US)
[locale-violation] ~141-~141: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...nd wait for another review. Hopefully, afterwards, your change will be accepted, merged i...
(AFTERWARDS_US)
[grammar] ~146-~146: Ensure spelling is correct
Context: ...e structure of the codebase, go to the developemenet reference
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
docs/client.md
[grammar] ~55-~55: Ensure spelling is correct
Context: ...ume() Takes volume: number Sets SFX folume to volume ##### stopSoundEffect() Tak...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.18.1)
docs/develop.md
14-14: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (7)
.gitignore (1)
14-14: Correctly excludes generated docs directory.Adding
site/aligns with the MkDocs configuration introduced in this PR. This directory will be generated during doc builds and should not be committed.docs/API.md (1)
1-94: Heading structure improvements support MkDocs navigation.Adjusting headings to consistent levels (moving subsections to H2) aligns with the new MkDocs documentation structure. Content and examples remain unchanged. This is a safe, beneficial restructuring.
docs/develop.md (2)
1-35: Well-structured development guide.The project structure breakdown is comprehensive and the document clearly guides contributors to related documentation. Content is appropriate and well-organized.
1-35: Run Prettier to auto-fix formatting.The pipeline reports formatting issues. Run
npx prettier --write docs/develop.mdto resolve.⛔ Skipped due to learnings
Learnt from: scottanderson Repo: openfrontio/OpenFrontIO PR: 1752 File: src/core/game/Game.ts:750-752 Timestamp: 2025-08-12T00:31:50.144Z Learning: In the OpenFrontIO codebase, changes to the PlayerInteraction interface (like adding canDonateGold and canDonateTroops flags) do not require corresponding updates to src/core/Schemas.ts or server serialization code.Learnt from: scottanderson Repo: openfrontio/OpenFrontIO PR: 1761 File: src/client/LocalPersistantStats.ts:24-31 Timestamp: 2025-08-09T05:14:19.147Z Learning: Files in the src/client directory contain browser-only code in the OpenFrontIO project, so browser APIs like localStorage are guaranteed to be available and don't need undefined guards.Learnt from: tnhnblgl Repo: openfrontio/OpenFrontIO PR: 875 File: src/client/index.html:396-402 Timestamp: 2025-05-26T09:52:52.465Z Learning: In the OpenFrontIO project, the correct path for icons from src/client/index.html is ../../resources/icons/, not /static/icons/ as the build process handles the path mapping differently.docs/getting_started.md (1)
1-146: Comprehensive and well-organized contributor guide.The step-by-step structure, prerequisites, and workflow instructions are clear and helpful. Once spelling errors are corrected and Prettier formatting is applied, this will be a valuable resource for new contributors.
docs/client.md (1)
1-97: Clear API reference documentation.The client-side module documentation provides helpful API surface descriptions. Once the spelling error is corrected and Prettier formatting is applied, this will be good reference material.
mkdocs.yml (1)
1-12: All referenced documentation files exist—no action required.The verification confirms that all files referenced in the mkdocs.yml navigation are present in the repository, including
contribute.md,server.md, andcore.md. The configuration is valid and the MkDocs build will succeed.
| # Client reference | ||
|
|
||
| ## Graphics | ||
|
|
||
| ## Style | ||
|
|
||
| ## Data | ||
|
|
||
| ## Sound | ||
|
|
||
| ### SoundManager.ts | ||
|
|
||
| #### enum SoundEffect | ||
|
|
||
| Enum of sound effects and their respective names | ||
|
|
||
| #### class SoundManager | ||
|
|
||
| ##### constructor() | ||
|
|
||
| This class takes no parameters to construct. | ||
|
|
||
| Uses Howler howl() to set the background music, and loads sound effects. | ||
|
|
||
| ##### playBackgroundMusic() | ||
|
|
||
| Plays the current music track. | ||
|
|
||
| ##### stopBackgroundMusic() | ||
|
|
||
| Stops the current music track. | ||
|
|
||
| ##### setBackgroundMusicVolume() | ||
|
|
||
| Takes a `volume: number` parameter. | ||
|
|
||
| Sets the music volume to `volume` | ||
|
|
||
| ##### loadSoundEffect() | ||
|
|
||
| Takes `name: SoundEffect` `src: string` | ||
|
|
||
| Loads or changes the src of a Howl sound effect. | ||
|
|
||
| ##### playSoundEffect() | ||
|
|
||
| Takes `name: SoundEffect` | ||
|
|
||
| Plays `name`. | ||
|
|
||
| ##### setSoundEffectsVolume() | ||
|
|
||
| Takes `volume: number` | ||
|
|
||
| Sets SFX folume to volume | ||
|
|
||
| ##### stopSoundEffect() | ||
|
|
||
| Takes `name: SoundEffect` | ||
|
|
||
| Stops name. | ||
|
|
||
| ##### unloadSoundEffect() | ||
|
|
||
| Takes `name: SoundEffect` | ||
|
|
||
| Unloads name and deletes it from `soundEffects` | ||
|
|
||
| ## Utilities | ||
|
|
||
| ### ReplaySpeedMultiplier.ts | ||
|
|
||
| #### enum ReplaySpeedMultiplier | ||
|
|
||
| Enum containing speed multiplier values | ||
|
|
||
| #### const defaultReplaySpeedMultiplier | ||
|
|
||
| The default replay speed multiplier | ||
|
|
||
| ### RenderUnitTypeOptions.ts | ||
|
|
||
| #### interface UnitTypeRenderContext | ||
|
|
||
| * `disabledUnits: UnitType[]` - array of disabled units | ||
| * `toggleUnit: (unit: UnitType, checked: boolean) => void` - function to toggle a unit's visibility | ||
|
|
||
| #### const unitOptions | ||
|
|
||
| array of object containing unit types and their translation keys | ||
|
|
||
| #### function renderUnitTypeOptions() | ||
|
|
||
| Takes a `UnitTypeRenderContext` interface as a parameter, returns `TemplateResult[]` | ||
|
|
||
| Returns an array of `TemplateResult`s (html strings) with each one holding the html for a unit type and a checkbox. | ||
|
|
There was a problem hiding this comment.
Run Prettier to auto-fix formatting.
The pipeline reports formatting issues. Run npx prettier --write docs/client.md to resolve.
🧰 Tools
🪛 GitHub Actions: 🧪 CI
[warning] 1-1: Prettier formatting issues found. Run 'npx prettier --write docs/client.md' to fix.
🪛 LanguageTool
[grammar] ~55-~55: Ensure spelling is correct
Context: ...ume() Takes volume: number Sets SFX folume to volume ##### stopSoundEffect() Tak...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🤖 Prompt for AI Agents
In docs/client.md around lines 1 to 97, the file has formatting/style issues
flagged by the CI; run a formatter to fix them by running "npx prettier --write
docs/client.md" (or your project's configured prettier command), then stage and
commit the updated file. Ensure your editor uses the repo Prettier config so
future edits follow the same rules.
|
|
||
| ### Setup | ||
|
|
||
| In github, fork [the repo](https://github.com/openfrontio/OpenFrontIO) onto your account. |
There was a problem hiding this comment.
Fix capitalization: "github" → "GitHub".
🧰 Tools
🪛 LanguageTool
[uncategorized] ~38-~38: The official name of this software platform is spelled with a capital “H”.
Context: ... learning how to use it. ### Setup In github, fork [the repo](https://github.com/ope...
(GITHUB)
🤖 Prompt for AI Agents
In docs/getting_started.md around line 38, change the lowercase "github" to the
correct capitalization "GitHub" in the sentence "In github, fork [the
repo](https://github.com/openfrontio/OpenFrontIO) onto your account." to fix the
branding/capitalization issue.
|
|
||
| Afterwards, if your PR is set as ready to be reviewed (not a draft) one of the maintainers will come and comment any needed changes. Discuss them further or implement the changes, and wait for another review. | ||
|
|
||
| Hopefully, afterwards, your change will be accepted, merged into main, and then later on, pushed out in an update to the live game! |
There was a problem hiding this comment.
Use American English spelling: "Afterwards" → "Afterward".
Applies to both lines 138 and 141.
🧰 Tools
🪛 LanguageTool
[locale-violation] ~138-~138: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ... changes are sensible, implement them. Afterwards, if your PR is set as ready to be revie...
(AFTERWARDS_US)
[locale-violation] ~141-~141: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...nd wait for another review. Hopefully, afterwards, your change will be accepted, merged i...
(AFTERWARDS_US)
🤖 Prompt for AI Agents
In docs/getting_started.md around lines 138 to 141, replace the
British/ambiguous "Afterwards" with the American English spelling "Afterward" on
both occurrences (line 138 and line 141) to ensure consistent American-English
usage; update the two words and run a quick spellcheck to confirm no other
instances remain.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (6)
docs/index.md (1)
13-13: Fix grammar: Add hyphen to "community-run wiki" and shorten phrasing.Line 13 has two issues: "community run wiki" should be hyphenated, and "In order to learn about" is verbose.
-In order to learn about game mechanics, check out the [community run wiki](https://openfront.miraheze.org), or even contribute to it! +To learn about game mechanics, check out the [community-run wiki](https://openfront.miraheze.org), or even contribute to it!docs/getting_started.md (5)
8-8: Use correct capitalization: "GitHub".The official name requires a capital "H".
-- github account +- GitHub account
38-38: Use correct capitalization: "GitHub".The official name requires a capital "H".
-In github, fork [the repo](https://github.com/openfrontio/OpenFrontIO) onto your account. +In GitHub, fork [the repo](https://github.com/openfrontio/OpenFrontIO) onto your account.
24-24: Use more concise language for "a lot of changes".Consider using simpler phrasing to reduce verbosity.
-If you would like to make a change, especially a larger one (like a new feature, a large rewrite, or similar), you will need to discuss with the contributors and the maintainers on IF the change should be implemented, and potentially HOW it should be implemented. You may make a change without this discussion, but there is a much larger chance that it will require a lot of changes, or be straight up rejected. +If you would like to make a change, especially a larger one (like a new feature, a large rewrite, or similar), you will need to discuss with the contributors and the maintainers on IF the change should be implemented, and potentially HOW it should be implemented. You may make a change without this discussion, but there is a much higher chance that it will require many changes or be rejected.
141-141: Use American English spelling: "Afterward" instead of "Afterwards".American English prefers "Afterward" (without the "s").
-Afterwards, if your PR is set as ready to be reviewed (not a draft) one of the maintainers will come and comment any needed changes. Discuss them further or implement the changes, and wait for another review. +Afterward, if your PR is set as ready to be reviewed (not a draft) one of the maintainers will come and comment any needed changes. Discuss them further or implement the changes, and wait for another review.
144-144: Use American English spelling: "Afterward" instead of "Afterwards".American English prefers "Afterward" (without the "s").
-Hopefully, afterwards, your change will be accepted, merged into main, and then later on, pushed out in an update to the live game! +Hopefully, afterward, your change will be accepted, merged into main, and then later on, pushed out in an update to the live game!
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (5)
docs/client.md(1 hunks)docs/develop.md(1 hunks)docs/getting_started.md(1 hunks)docs/index.md(1 hunks)mkdocs.yml(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (3)
- mkdocs.yml
- docs/develop.md
- docs/client.md
🧰 Additional context used
🪛 LanguageTool
docs/getting_started.md
[style] ~24-~24: Consider using a synonym to be more concise.
Context: ...much larger chance that it will require a lot of changes, or be straight up rejected. T...
(A_LOT_OF)
[locale-violation] ~141-~141: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ... changes are sensible, implement them. Afterwards, if your PR is set as ready to be revie...
(AFTERWARDS_US)
[locale-violation] ~144-~144: In American English, ‘afterward’ is the preferred variant. ‘Afterwards’ is more commonly used in British English and other dialects.
Context: ...nd wait for another review. Hopefully, afterwards, your change will be accepted, merged i...
(AFTERWARDS_US)
docs/index.md
[style] ~12-~12: Consider a more concise word here.
Context: ... Starting Guide! In order to learn about game mechanics, check out t...
(IN_ORDER_TO_PREMIUM)
[grammar] ~13-~13: Use a hyphen to join words.
Context: ...game mechanics, check out the [community run wiki](https://openfront.miraheze.org...
(QB_NEW_EN_HYPHEN)
🔇 Additional comments (1)
docs/index.md (1)
8-8: Verify contributing file name matches your file system.The link points to
contribute.md, but PR objectives reference creatingCONTRIBUTING.md. Ensure the file name is consistent across the documentation.
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
docs/develop.md (1)
34-36: Expand or clarify the "Technologies used" section.This section lists only Lit, but the documentation mentions TypeScript, Jest, and other technologies elsewhere. Either expand this section to be comprehensive or remove it if it's meant to highlight only key frameworks.
Consider adding the other key technologies mentioned in the document:
## Technologies used - [Lit](https://lit.dev/) for creating usable html objects (usually `TemplateResult`) from strings. +- [TypeScript](https://www.typescriptlang.org/) for static typing. +- [Jest](https://jestjs.io/) for regression testing.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
docs/develop.md(1 hunks)
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
docs/develop.md
38-38: Images should have alternate text (alt text)
(MD045, no-alt-text)
🔇 Additional comments (1)
docs/develop.md (1)
17-17: All referenced documentation files exist - no action needed.The verification confirms that
docs/core.md,docs/client.md, anddocs/server.mdall exist in the docs directory. The documentation links indocs/develop.mdare valid and will not break.
|
|
||
| - [Lit](https://lit.dev/) for creating usable html objects (usually `TemplateResult`) from strings. | ||
|
|
||
|  |
There was a problem hiding this comment.
Add alt text to the image for accessibility.
The image is missing alt text, which is required for accessibility. Users with screen readers and others will not understand what the image depicts.
Apply this diff to add descriptive alt text:
-
+Adjust the alt text to accurately describe what the image shows.
📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
|  | |
|  |
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
38-38: Images should have alternate text (alt text)
(MD045, no-alt-text)
🤖 Prompt for AI Agents
In docs/develop.md around line 38 the image tag lacks alt text which hinders
accessibility; update the markdown image to include a concise, descriptive alt
attribute (e.g., ) that accurately
describes the image content so screen readers can convey its meaning.
3 participants
Description:
Adds documentation.
Aims to close #1720
Ideally, the docs would be compiled into a nice github pages website by the repo maintainer
Requirnments are python and the mkdocs package
https://www.mkdocs.org/user-guide/deploying-your-docs/
Currently a WIP
Please put your Discord username so you can be contacted if a bug or regression is found:
Lavodan