docs: add/improve overview pgs for backend, frontend, schema, & SDKs#4075
docs: add/improve overview pgs for backend, frontend, schema, & SDKs#4075arkid15r merged 15 commits intoOWASP:mainfrom
Conversation
Signed-off-by: Muhammad Hassaan Saleem <iamhassaans@gmail.com>
Summary by CodeRabbit
WalkthroughThis PR consolidates and improves project documentation by adding comprehensive README files for backend and frontend components, creating dedicated documentation pages for API, NestBot, and Schema, replacing redundant documentation with include directives, updating MkDocs navigation structure, and configuring Docker Compose to mount documentation sources. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
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 |
github-actions
bot
added
docs
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
arkid15r
left a comment
arkid15r
left a comment
There was a problem hiding this comment.
Great work, let's reshape it a bit and cover NestBot too (same approach, README.md in the repository + reuse it in docs section).
mkdocs.yaml
Outdated
| @@ -3,6 +3,14 @@ nav: | |||
| - Home: index.md | |||
There was a problem hiding this comment.
For the main page we should reuse (maybe just include) the root repository README.md
mkdocs.yaml
Outdated
| @@ -3,6 +3,14 @@ nav: | |||
| - Home: index.md | |||
| - Code of Conduct: code-of-conduct.md | |||
There was a problem hiding this comment.
Can we also use one from the repository root?
docs/schema/overview.md
Outdated
|
|
||
| --- | ||
|
|
||
| ## OWASP Schema Package |
There was a problem hiding this comment.
Keep this section, delete the rest.
docs/sdks/overview.md
Outdated
There was a problem hiding this comment.
Let's rename it to api, add backend/apps/api/README.md file similar to backend/frontend overview. We should also keep SDKs info (maybe just in overview.md instead of the README.md)
mkdocs.yaml
Outdated
| @@ -3,6 +3,14 @@ nav: | |||
| - Home: index.md | |||
| - Code of Conduct: code-of-conduct.md | |||
| - Contributing: contributing.md | |||
There was a problem hiding this comment.
Let's move code of conduct and contributing to the main page menu from this horizontal menu. Keep only Home, API, Backend, Frontend, NestBot, Schema here.
Signed-off-by: Muhammad Hassaan Saleem <iamhassaans@gmail.com>
hassaansaleem28
dismissed stale reviews from coderabbitai[bot] and cubic-dev-ai[bot]
via
c977850
Signed-off-by: Muhammad Hassaan Saleem <iamhassaans@gmail.com>
|
Hi @arkid15r, LET ME KNOW IF FURTHER CHANGES ARE REQUIRED. |
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
backend/apps/slack/README.md (1)
25-31: Consider clarifying where to run the Make targets.Small clarity win: explicitly say these commands are run from the repository root.
✏️ Suggested docs tweak
-The project provides `Makefile` targets to manage Slack data: +Run these `Makefile` targets from the repository root to manage Slack data:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@backend/apps/slack/README.md` around lines 25 - 31, Update the README to clarify that the Makefile targets (e.g., make slack-sync-data, make slack-sync-messages, make slack-export-data) must be executed from the repository root; add one short sentence after the table stating "Run these commands from the repository root where the Makefile lives" and, if helpful, mention prerequisite steps (e.g., ensure you have the Makefile and required environment variables set) so readers know why the root is required.
🤖 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/api/overview.md`:
- Around line 9-14: Add a blank line immediately after the headings "### 1.
Unique `operationId`" and "### 2. Stable Authentication Class Name" to satisfy
MD022, and remove trailing spaces at the ends of the list lines (the lines under
the second heading that end with extra whitespace) to satisfy MD009; ensure the
headings remain followed by a single blank line and the list lines end cleanly
with no trailing spaces.
---
Nitpick comments:
In `@backend/apps/slack/README.md`:
- Around line 25-31: Update the README to clarify that the Makefile targets
(e.g., make slack-sync-data, make slack-sync-messages, make slack-export-data)
must be executed from the repository root; add one short sentence after the
table stating "Run these commands from the repository root where the Makefile
lives" and, if helpful, mention prerequisite steps (e.g., ensure you have the
Makefile and required environment variables set) so readers know why the root is
required.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
README.mdbackend/apps/api/README.mdbackend/apps/slack/README.mddocker-compose/local/compose.yamldocs/api/overview.mddocs/code-of-conduct.mddocs/contributing.mddocs/index.mddocs/nestbot/overview.mddocs/schema/overview.mdmkdocs.yaml
✅ Files skipped from review due to trivial changes (6)
- docs/index.md
- docs/code-of-conduct.md
- docs/nestbot/overview.md
- backend/apps/api/README.md
- docs/contributing.md
- README.md
🚧 Files skipped from review as they are similar to previous changes (2)
- docker-compose/local/compose.yaml
- docs/schema/overview.md
Signed-off-by: Muhammad Hassaan Saleem <iamhassaans@gmail.com>
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 3 files (changes from recent commits).
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name=".pre-commit-config.yaml">
<violation number="1" location=".pre-commit-config.yaml:81">
P2: `language: system` for `markdownlint` bypasses pre-commit-managed environments, making hook execution dependent on host PATH and reducing reproducibility/portability.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
Signed-off-by: Muhammad Hassaan Saleem <iamhassaans@gmail.com>
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 @.pre-commit-config.yaml:
- Line 81: The markdownlint pre-commit hook currently specifies "language:
system" which assumes markdownlint is preinstalled and will break CI; update the
markdownlint hook (the entry named markdownlint in .pre-commit-config.yaml) by
removing the "language: system" field so pre-commit manages the environment, or
alternatively keep "language: system" but add explicit markdownlint installation
to your CI workflow; ensure the change targets the markdownlint hook
configuration and re-run pre-commit to verify hooks install correctly.
In `@docs/api/overview.md`:
- Line 1: Add a mkdocs.yml to enable the snippets plugin (or update the existing
mkdocs.yml) so the include syntax `--8<-- "backend/apps/api/README.md"` in
docs/api/overview.md works: create or update mkdocs.yml to list the MkDocs
Snippets plugin under plugins and ensure the docs_dir includes the docs path;
verify plugin configuration supports snippet paths (so files like
backend/apps/api/README.md and backend/apps/api/rest/auth/api_key.py can be
resolved) and run mkdocs build to confirm the includes render correctly.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (3)
.pre-commit-config.yamlbackend/apps/slack/README.mddocs/api/overview.md
🚧 Files skipped from review as they are similar to previous changes (1)
- backend/apps/slack/README.md
|
@coderabbitai review this pull. |
|
✅ Actions performedReview triggered.
|
Signed-off-by: Muhammad Hassaan Saleem <iamhassaans@gmail.com>
|
Hi @arkid15r. |
|
There was a problem hiding this comment.
🧹 Nitpick comments (2)
docs/schema/index.md (1)
3-3: Tighten the opening sentence for clarity.At Line 3, the phrasing is a bit awkward; a small rewrite reads cleaner.
✍️ Suggested edit
-OWASP Nest maintains the `owasp-schema` Python package for OWASP entities structure standardization. +OWASP Nest maintains the `owasp-schema` Python package to standardize OWASP entity structures.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/schema/index.md` at line 3, The opening sentence in docs/schema/index.md is awkward; rewrite it to a tighter, clearer form such as stating that "OWASP Nest provides the owasp-schema Python package to standardize OWASP entity structures" (or similar), replacing the current line that mentions "maintains the `owasp-schema` Python package for OWASP entities structure standardization" so the phrasing is more direct and readable.backend/README.md (1)
9-9: Remove hard-coded Django version from README.Line 9 lists
Django 6.x, butbackend/pyproject.tomlspecifiesdjango = "^6.0"(allowing minor updates to 6.0.3), and the lock file pins 6.0.3. Replace the version with justDjangoand point readers topyproject.tomlas the source-of-truth for dependency requirements.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@backend/README.md` at line 9, Replace the hard-coded "Django 6.x" entry in README (the table row containing "Django 6.x") with a generic "Django" and add a short note or parenthetical pointing readers to backend/pyproject.toml as the source-of-truth for the exact pinned version; update the table cell content so it no longer lists a specific version but references pyproject.toml for dependency details.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@backend/README.md`:
- Line 9: Replace the hard-coded "Django 6.x" entry in README (the table row
containing "Django 6.x") with a generic "Django" and add a short note or
parenthetical pointing readers to backend/pyproject.toml as the source-of-truth
for the exact pinned version; update the table cell content so it no longer
lists a specific version but references pyproject.toml for dependency details.
In `@docs/schema/index.md`:
- Line 3: The opening sentence in docs/schema/index.md is awkward; rewrite it to
a tighter, clearer form such as stating that "OWASP Nest provides the
owasp-schema Python package to standardize OWASP entity structures" (or
similar), replacing the current line that mentions "maintains the `owasp-schema`
Python package for OWASP entities structure standardization" so the phrasing is
more direct and readable.
ℹ️ Review info
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (11)
.gitignorebackend/README.mdbackend/apps/api/README.mdbackend/apps/slack/README.mddocs/api/index.mddocs/backend/index.mddocs/frontend/index.mddocs/nestbot/index.mddocs/schema/index.mdfrontend/README.mdmkdocs.yaml
✅ Files skipped from review due to trivial changes (3)
- docs/frontend/index.md
- docs/backend/index.md
- docs/nestbot/index.md
🚧 Files skipped from review as they are similar to previous changes (1)
- frontend/README.md
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #4075 +/- ##
=======================================
Coverage 99.80% 99.80%
=======================================
Files 519 519
Lines 16031 16031
Branches 2143 2143
=======================================
Hits 16000 16000
Misses 26 26
Partials 5 5
Flags with carried forward coverage won't be shown. Click here to find out more. Continue to review full report in Codecov by Sentry.
🚀 New features to boost your workflow:
|
2 participants
Fixes #3528
This PR addresses the documentation gaps for first-time contributors by adding minimal, practical overviews for the main project components.
Changes included:
backend/andfrontend/directories.docs/for the Backend, Frontend, Schema, and API SDKs.Checklist
make check-testlocally: all warnings addressed, tests passed