MPT-20094 reorganize repository documentation#299
Merged
Conversation
📝 WalkthroughWalkthroughRestructures repository documentation and developer workflow toward a Docker-first model: replaces Python-specific Copilot guidance with a generic entry point, consolidates usage and docs into new Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 inconclusive)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
d3rky
force-pushed
the
feature/MPT-20094/generate-technical-documentation-for-the-repo
branch
from
325c719 to
7e9eded
Compare
![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
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/contributing.md`:
- Around line 8-12: Update the links listed in docs/contributing.md to use the
repository’s canonical standards: replace the current Python, packages, pull
requests, documentation and Makefile links with the shared standards references
— specifically point to standards/contributing-standard.md,
standards/pull-request-guidelines.md, standards/python-style-guide.md, and
standards/testing-standard.md where applicable — so the contributor guidance
matches the repository baseline; ensure the list entries and link text reflect
these canonical filenames and remove or consolidate any redundant/non-canonical
links.
In `@docs/testing.md`:
- Around line 3-5: Update the broken shared-standard link in docs/testing.md by
replacing the reference to "standards/unittests.md" with the canonical
"standards/testing-standard.md"; locate the link text string
"standards/unittests.md" in docs/testing.md and update it so the sentence reads
and links to standards/testing-standard.md (ensure any surrounding Markdown
formatting and the existing sentence about repository-specific testing behavior
remain unchanged).
🪄 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: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 3875cb3e-eb72-41e3-8ddc-56fb1ebbe2b9
📒 Files selected for processing (10)
.github/workflows/copilot-instructions.mdAGENTS.mdREADME.mddocs/PROJECT_DESCRIPTION.mddocs/contributing.mddocs/documentation.mddocs/local-development.mddocs/testing.mddocs/usage.mdpyproject.toml
💤 Files with no reviewable changes (1)
- docs/PROJECT_DESCRIPTION.md
There was a problem hiding this comment.
Actionable comments posted: 2
♻️ Duplicate comments (1)
docs/contributing.md (1)
8-12:⚠️ Potential issue | 🟡 MinorUse the repository’s canonical shared-standard links.
These links still don’t match the standard pages this repo has established as the baseline for contributor guidance. Please align them to the canonical targets.
Suggested link updates
-- [Python coding conventions](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md) -- [Packages and dependencies](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/packages-and-dependencies.md) -- [Pull requests](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-requests.md) -- [Repository documentation](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/documentation.md) -- [Makefile structure](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/makefiles.md) +- [Contributing standard](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/contributing-standard.md) +- [Pull request guidelines](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-request-guidelines.md) +- [Python style guide](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-style-guide.md) +- [Testing standard](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/testing-standard.md)Based on learnings: "Follow the pull request guidelines defined in
standards/pull-request-guidelines.md... Applies to **/.py:standards/python-style-guide.md... Applies to **/test_.py:standards/testing-standard.md."🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/contributing.md` around lines 8 - 12, Replace the non-canonical links in the contributing page that point to legacy files (e.g. python-coding.md, packages-and-dependencies.md, pull-requests.md, documentation.md, makefiles.md) with the repository’s canonical standard targets: use standards/python-style-guide.md for Python conventions (and standards/testing-standard.md for test files), standards/pull-request-guidelines.md for PR guidance, and the appropriate canonical standards pages for packages/dependencies, documentation, and Makefile structure; update the link texts/URLs in the list so they reference those canonical files.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/usage.md`:
- Around line 35-37: The sample .env entry uses a token-like value
(MPT_API_TOKEN=eyJhbGciOiJSUzI1NiIs...) which can trigger secret scanners;
replace that literal JWT-like string with a clear placeholder such as
MPT_API_TOKEN=<YOUR_API_TOKEN> or MPT_API_TOKEN=REPLACE_WITH_API_TOKEN and
optionally add a short comment showing format if needed (e.g., "# paste your API
token here"). Update the example line containing MPT_API_TOKEN and ensure other
env examples (e.g., MPT_API_BASE_URL) follow the same non-secret placeholder
approach.
- Around line 119-120: Update the sentence that references the "MPT OpenAPI
spec" so it includes a direct markdown link to the actual OpenAPI spec URL (or
internal spec file) alongside the existing architecture.md link; locate the
sentence "See [architecture.md](architecture.md) for the repository structure
and the MPT OpenAPI spec for the upstream endpoint contract." in docs/usage.md
and change the text so "MPT OpenAPI spec" is a clickable link pointing to the
spec (e.g., replace plain text with [MPT OpenAPI spec](<SPEC_URL_OR_PATH>)).
---
Duplicate comments:
In `@docs/contributing.md`:
- Around line 8-12: Replace the non-canonical links in the contributing page
that point to legacy files (e.g. python-coding.md, packages-and-dependencies.md,
pull-requests.md, documentation.md, makefiles.md) with the repository’s
canonical standard targets: use standards/python-style-guide.md for Python
conventions (and standards/testing-standard.md for test files),
standards/pull-request-guidelines.md for PR guidance, and the appropriate
canonical standards pages for packages/dependencies, documentation, and Makefile
structure; update the link texts/URLs in the list so they reference those
canonical files.
🪄 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: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: eeb31185-0d0f-44d0-851d-efc4de9d338c
📒 Files selected for processing (10)
.github/workflows/copilot-instructions.mdAGENTS.mdREADME.mddocs/PROJECT_DESCRIPTION.mddocs/contributing.mddocs/documentation.mddocs/local-development.mddocs/testing.mddocs/usage.mdpyproject.toml
💤 Files with no reviewable changes (1)
- docs/PROJECT_DESCRIPTION.md
✅ Files skipped from review due to trivial changes (2)
- .github/workflows/copilot-instructions.md
- docs/documentation.md
🚧 Files skipped from review as they are similar to previous changes (4)
- pyproject.toml
- docs/local-development.md
- docs/testing.md
- AGENTS.md
d3rky
force-pushed
the
feature/MPT-20094/generate-technical-documentation-for-the-repo
branch
from
7e9eded to
4238e8e
Compare
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/contributing.md (1)
8-10:⚠️ Potential issue | 🟡 MinorAlign shared-standard links with the repository’s canonical standard filenames.
The current targets (
python-coding.md,pull-requests.md) still don’t match the canonical standards previously established for this repo (python-style-guide.md,pull-request-guidelines.md; plus includecontributing-standard.mdin this section).Based on learnings: "Follow the contributing standards defined in
standards/contributing-standard.md..." and "Follow the pull request guidelines defined instandards/pull-request-guidelines.md..." and "Applies to **/*.py: ...standards/python-style-guide.md".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/contributing.md` around lines 8 - 10, Update the three links in the list to point to the repo's canonical standard filenames: replace the `python-coding.md` link with `python-style-guide.md`, replace `pull-requests.md` with `pull-request-guidelines.md`, and add an entry for `contributing-standard.md` (e.g., include a new bullet "Contributing standards" linking to `standards/contributing-standard.md`) so the list contains: python-style-guide.md, packages-and-dependencies.md (unchanged), pull-request-guidelines.md, and contributing-standard.md; ensure the visible link text matches the target filenames for clarity.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@pyproject.toml`:
- Line 56: The package include list currently only contains "mpt_api_client"
which excludes the README referenced by project.readme; update the build include
so README.md is packaged into both sdist and wheel by adding "README.md" (and
optionally other docs like "LICENSE") to the include list used for sdist/wheel
generation so that the sdist contains the README and wheel builds from sdist
succeed; specifically modify the include = ["mpt_api_client"] entry in
pyproject.toml to also include "README.md" (and any other necessary files).
---
Duplicate comments:
In `@docs/contributing.md`:
- Around line 8-10: Update the three links in the list to point to the repo's
canonical standard filenames: replace the `python-coding.md` link with
`python-style-guide.md`, replace `pull-requests.md` with
`pull-request-guidelines.md`, and add an entry for `contributing-standard.md`
(e.g., include a new bullet "Contributing standards" linking to
`standards/contributing-standard.md`) so the list contains:
python-style-guide.md, packages-and-dependencies.md (unchanged),
pull-request-guidelines.md, and contributing-standard.md; ensure the visible
link text matches the target filenames for clarity.
🪄 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: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: cb454008-8e27-40ad-92c6-d2dda167154f
📒 Files selected for processing (10)
.github/workflows/copilot-instructions.mdAGENTS.mdREADME.mddocs/PROJECT_DESCRIPTION.mddocs/contributing.mddocs/documentation.mddocs/local-development.mddocs/testing.mddocs/usage.mdpyproject.toml
💤 Files with no reviewable changes (1)
- docs/PROJECT_DESCRIPTION.md
✅ Files skipped from review due to trivial changes (5)
- .github/workflows/copilot-instructions.md
- docs/testing.md
- docs/documentation.md
- README.md
- docs/usage.md
🚧 Files skipped from review as they are similar to previous changes (2)
- AGENTS.md
- docs/local-development.md
AI Generated. Rework the repository documentation structure around a developer-focused usage guide, shared-standard links, and a concise README. Replace PROJECT_DESCRIPTION with usage.md, add documentation rules, and keep Docker-based workflow guidance in the topic-specific docs.
d3rky
force-pushed
the
feature/MPT-20094/generate-technical-documentation-for-the-repo
branch
from
4238e8e to
4a2fcbe
Compare
|
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
docs/contributing.md (1)
8-10:⚠️ Potential issue | 🟡 MinorUse canonical shared-standard filenames to avoid link drift.
Line 8 and Line 10 point to
standards/python-coding.mdandstandards/pull-requests.md, but repository guidance referencesstandards/python-style-guide.mdandstandards/pull-request-guidelines.md. Please align these links to the canonical filenames.Suggested fix
-- [Python coding conventions](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-coding.md) +- [Python coding conventions](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/python-style-guide.md) ... -- [Pull requests](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-requests.md) +- [Pull requests](https://github.com/softwareone-platform/mpt-extension-skills/blob/main/standards/pull-request-guidelines.md)Based on learnings: "Follow the pull request guidelines defined in
standards/pull-request-guidelines.md..." and "Applies to **/*.py : Follow the coding style and conventions defined instandards/python-style-guide.md...".🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/contributing.md` around lines 8 - 10, Update the two broken links in the markdown list: replace references to standards/python-coding.md with standards/python-style-guide.md and replace standards/pull-requests.md with standards/pull-request-guidelines.md so the link targets match the canonical filenames; also scan the same file for any other occurrences of these old names and update them to the canonical filenames to avoid future link drift.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/testing.md`:
- Around line 39-40: The docs/testing.md claim that "Branch coverage enabled" is
incorrect because pytest/cov is not configured with --cov-branch in
pyproject.toml; either add --cov-branch to the pytest-cov invocation in
pyproject.toml (so pytest respects branch coverage) or remove/update the "Branch
coverage enabled" statement in docs/testing.md to reflect current configuration;
reference the pytest/cov flag (--cov-branch) and the docs/testing.md statement
when making the change.
---
Duplicate comments:
In `@docs/contributing.md`:
- Around line 8-10: Update the two broken links in the markdown list: replace
references to standards/python-coding.md with standards/python-style-guide.md
and replace standards/pull-requests.md with standards/pull-request-guidelines.md
so the link targets match the canonical filenames; also scan the same file for
any other occurrences of these old names and update them to the canonical
filenames to avoid future link drift.
🪄 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: Repository YAML (base), Organization UI (inherited)
Review profile: CHILL
Plan: Pro
Run ID: 02abeefe-56d7-4b1f-97ca-62def285dfc3
📒 Files selected for processing (10)
.github/workflows/copilot-instructions.mdAGENTS.mdREADME.mddocs/PROJECT_DESCRIPTION.mddocs/contributing.mddocs/documentation.mddocs/local-development.mddocs/testing.mddocs/usage.mdpyproject.toml
💤 Files with no reviewable changes (1)
- docs/PROJECT_DESCRIPTION.md
✅ Files skipped from review due to trivial changes (3)
- pyproject.toml
- docs/documentation.md
- docs/usage.md
🚧 Files skipped from review as they are similar to previous changes (4)
- .github/workflows/copilot-instructions.md
- docs/local-development.md
- AGENTS.md
- README.md
d3rky
deleted the
feature/MPT-20094/generate-technical-documentation-for-the-repo
branch
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.
🤖 AI-generated PR — Please review carefully.
Summary
Testing
Closes MPT-20094
Closes MPT-20094
Release Notes
New documentation structure: Replaced
docs/PROJECT_DESCRIPTION.mdwith a new developer-focuseddocs/usage.mdproviding installation, configuration, and usage examples for synchronous and asynchronous client patterns.README.md refocus: Simplified README to a concise entry point with a new Documentation section linking to key resources (AGENTS.md, usage guide, architecture, testing, contributing docs, and OpenAPI spec). Removed quality badges and usage code snippets.
AGENTS.md reorganization: Restructured with a "Documentation Reading Order" guide, expanded "Key Commands" table with Docker-based targets, and added "Repository Rules" section linking to shared standards from mpt-extension-skills. Updated API reference wording to reference "MPT OpenAPI spec."
AI agent configuration update: Updated
.github/workflows/copilot-instructions.mdfrom Python-specific coding conventions to a repository-wide instruction pointing to AGENTS.md.Contributing guidance consolidation: Replaced local contribution content in
docs/contributing.mdwith repository-specific guidance pointing to shared engineering standards. Added explicit "Development Model" using Docker and "Repository-Specific Expectations" for code changes.Documentation standards definition: Added new
docs/documentation.mddefining repository documentation rules, specifyingREADME.mdas human entry point,AGENTS.mdas AI entry point, and mandating use of shared standards from mpt-extension-skills instead of local copies.Docker-centric local development: Refactored
docs/local-development.mdto emphasize Docker-only workflow withmake bashandmake runcommands; simplified environment variables section with cross-references to usage.md and e2e_tests.md.Testing documentation updates: Reorganized
docs/testing.mdto clarify test scopes, document Docker-basedmakecommand behavior, and define repository constraints for E2E testing and coverage expectations.Build configuration updates: Updated
pyproject.tomlto reference README.md instead of docs/PROJECT_DESCRIPTION.md as project readme, with adjusted Hatch packaging includes for distributions.