docs: add generated documentation#2755
Open
myakove wants to merge 1 commit into
Open
Conversation
WalkthroughThis PR adds a complete static documentation site under ChangesDocumentation Site Infrastructure
Documentation Content Pages
Estimated code review effort: 2 (Simple) | ~15 minutes Suggested labels: 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✨ Finishing Touches📝 Generate docstrings
🧪 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 |
|
Report bugs in Issues Welcome! 🎉This pull request will be automatically processed with the following features: 🔄 Automatic Actions
📋 Available CommandsPR Status Management
Review & Approval
Testing & Validation
Cherry-pick Operations
Branch Management
Label Management
✅ Merge RequirementsThis PR will be automatically approved when the following conditions are met:
📊 Review ProcessApprovers and ReviewersApprovers:
Reviewers:
Available Labels
AI Features
Security Checks
💡 Tips
For more information, please refer to the project documentation or contact the maintainers. |
PR Summary by QodoPublish generated Docsfy documentation site and exclude it from secret scanning
AI Description
Diagram
High-Level Assessment
Files changed (57)
|
Code Review by Qodo
1. Docs secret-scan bypass
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
| "--exclude-files=class_generator/schema/*", | ||
| "--exclude-files=class_generator/__k8s-openapi-.*.json", | ||
| "--exclude-files=fake_kubernetes_client/__resources-mappings.json", | ||
| "--exclude-files=docs/.*", |
There was a problem hiding this comment.
1. Docs secret-scan bypass 🐞 Bug ⛨ Security
The PR broadly reduces secret-scanning coverage by excluding the entire docs/ directory from detect-secrets and adding docs/ to the gitleaks allowlist, creating a blind spot where real credentials pasted into documentation would not be flagged. Additionally, the gitleaks allowlist entry’s id/description still suggests it only skips class_generator/schema, making the expanded ignore scope easy to miss and less intentional/visible during review.
Agent Prompt
## Issue description
`docs/` is broadly excluded/allowlisted from secret scanning, which creates a blind spot where real secrets can slip through undetected, and the gitleaks allowlist entry metadata (id/description) no longer matches what it actually ignores after adding `docs/`, reducing visibility/intent.
## Issue Context
The docs are generated and include placeholder token/password-like strings, which likely motivated the exclusions to avoid false positives. However, excluding/allowlisting the entire `docs/` tree is broader than necessary, and combining unrelated ignore scopes (schema + docs) under a label that only mentions schema makes future ignore expansions easier to miss during review.
## Fix Focus Areas
- `.pre-commit-config.yaml[36-46]`
- `.gitleaks.toml[4-8]`
## Suggested fix approach
1. Replace the blanket `docs/.*` exclusion with a narrower rule (e.g., exclude only generated `*.html` and/or `docs/search-index.json`, while still scanning `*.md`), or exclude only specific known false-positive files.
2. For gitleaks, prefer allowlisting only known placeholder patterns (where supported) rather than all of `docs/`, and ensure any path-based allowlisting is as narrow as practical.
3. Update the existing gitleaks allowlist `id` and `description` to accurately reflect what it ignores, or split it into two entries (one for `class_generator/schema/`, one for `docs/`) so the purpose and scope are explicit.
4. Add a short comment explaining why the exclusions exist and what content is expected/safe in generated docs to prevent future over-expansion.
ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 13
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
docs/quickstart.md (1)
466-474: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winRemove the extra
cm.create()inside the context manager.
with ConfigMap(...) as cm:already manages creation/cleanup, so this second call is redundant and can double-submit the request. If the fake-client path is special, say so explicitly.Proposed fix
with ConfigMap( client=client, name="test-config", namespace="default", data={"key": "value"}, ) as cm: - cm.create() print(f"Created (fake): {cm.name}")🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/quickstart.md` around lines 466 - 474, The quickstart example is calling cm.create() redundantly inside the ConfigMap context manager, which can double-submit the request. Update the ConfigMap usage so the with ConfigMap(...) as cm: block relies on the context manager’s built-in create/cleanup behavior, and remove the extra create() call unless the fake-client path truly needs special handling. If it does, make that exception explicit in the example near ConfigMap.
♻️ Duplicate comments (1)
docs/pod-execution-and-logs.html (1)
269-274: 📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick winSame leaked AI-generation scratch notes rendered into the HTML output.
This is the rendered downstream of the leaked commentary in
docs/pod-execution-and-logs.md(lines 1-12). Fixing the Markdown source and regenerating this HTML will resolve both.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/pod-execution-and-logs.html` around lines 269 - 274, The HTML output contains leaked AI scratch notes that should not be rendered; remove the commentary from the source documentation and regenerate the page. Update the `docs/pod-execution-and-logs.md` content that feeds this HTML, then rebuild so the rendered output no longer includes the exploratory sentences in the affected section.
🧹 Nitpick comments (5)
docs/mcp-server-integration.md (1)
94-94: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueFenced code blocks missing language identifier (MD040).
Several prompt-example code fences lack a language tag, flagged by markdownlint. Add
text(or similar) to satisfy MD040 and keep consistent Docsify syntax highlighting.Example fix
-``` +```text Prompt: "List all pods in the openshift-monitoring namespace with label app=prometheus"Also applies to: 117-117, 138-138, 183-183, 260-260, 282-282, 306-306, 329-329, 350-350
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/mcp-server-integration.md` at line 94, Several fenced prompt-example blocks in the MCP server integration docs are missing a language tag and are failing MD040. Update the affected fenced code blocks in the markdown so they use a language identifier such as text, keeping the existing prompt content intact and ensuring consistency with Docsify syntax highlighting. Focus on the prompt-example fences throughout the document rather than changing the surrounding prose.Source: Linters/SAST tools
README.md (1)
3-4: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winNew docs link conflicts with existing “Docs:” references.
The README now has three separate pointers to documentation: the new GitHub Pages link (Line 3), the existing
Docs:line pointing to readthedocs.io (Line 7), and the## docssection also pointing to readthedocs.io (Line 90). This is confusing for readers as to which is canonical/up to date; consider consolidating or clarifying which is the source of truth.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@README.md` around lines 3 - 4, The README now has multiple documentation pointers that conflict, so consolidate them into a single canonical source or clearly label one as primary and the others as secondary. Update the top-level docs link and the existing “Docs:” reference plus the “## docs” section so they all point to the same authoritative destination, and use consistent wording in README.md to remove ambiguity for readers..pre-commit-config.yaml (1)
45-45: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winSame broad-exclusion concern as
.gitleaks.toml.
--exclude-files=docs/.*disables detect-secrets for the entiredocs/tree rather than just the generated pages containing placeholder tokens, reducing the secret-scanning safety net for that directory going forward.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.pre-commit-config.yaml at line 45, The detect-secrets exclude in the pre-commit config is too broad and disables scanning for the whole docs tree. Narrow the pattern in the pre-commit hook configuration so it only skips the specific generated pages or placeholder-token files, not every path under docs/; keep the change localized in the hook entry that currently uses the docs/.* exclusion.docs/assets/style.css (1)
70-71: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winStylelint
value-keyword-caseflags mixed-case font names.Static analysis flags
BlinkMacSystemFont,Roboto,Arial,SFMono-Regular,Menlo, andConsolasfor keyword casing. These are conventionally-cased system/font-family identifiers, so lowercasing them would hurt readability; the fix should exemptfont-familyfrom thevalue-keyword-caserule (e.g.ignoreProperties: ["font-family"]or a targeted disable comment) rather than changing the values themselves.🎨 Suggested inline disable
+ /* stylelint-disable value-keyword-case */ --font-sans: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif, "Apple Color Emoji", "Segoe UI Emoji"; --font-mono: "SF Mono", SFMono-Regular, ui-monospace, "DejaVu Sans Mono", Menlo, Consolas, monospace; + /* stylelint-enable value-keyword-case */🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/assets/style.css` around lines 70 - 71, The mixed-case font-family values in the style sheet are being flagged by the value-keyword-case lint rule, but the identifiers in the font stack should remain unchanged. Update the Stylelint configuration to ignore font-family for value-keyword-case, or add a targeted disable around the relevant --font-sans and --font-mono declarations, rather than lowercasing the font names themselves.Source: Linters/SAST tools
.gitleaks.toml (1)
7-7: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winBroad directory exclusion disables gitleaks scanning entirely for
docs/.
pathsfully excludes matching files from scanning (independent ofregexex), so any file anywhere underdocs/— including hand-authored.mdfiles, JS assets, etc. — is now unscanned, not just the generated pages with placeholder tokens. A narrower pattern (e.g. targeting only the generated HTML/MD pages or a documented placeholder-token pattern) would preserve coverage for genuinely committed secrets in docs.🔒️ Suggested narrower allowlist
-paths = ['''class_generator/schema/''', '''docs/'''] +paths = ['''class_generator/schema/''', '''docs/.*\.(html|md)$''']🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.gitleaks.toml at line 7, The gitleaks allowlist is too broad because the docs/ entry in the paths list excludes every file under docs/ from scanning. Narrow the exclusion in .gitleaks.toml so only the generated placeholder-token docs are skipped, using a more specific path/pattern near the existing class_generator/schema/ rule, and preserve scanning for authored docs assets such as markdown and JS.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/class-generator-cli.md`:
- Around line 663-669: The schema-files summary in the CLI docs is inconsistent
with the table contents. Update the introductory sentence around the schema file
list so it matches the three entries shown, and make sure the description around
the schema management section stays aligned with the symbols named in the table
(`__resources-mappings.json.gz`, `_definitions.json`, and
`__cluster_version__.txt`).
- Around line 25-28: The shell completion tip currently mixes bash and zsh in
one snippet and hard-codes zsh_source, so update the docs to provide separate
completion examples for bash and zsh. In the class-generator-cli.md content,
replace the single command with two clearly labeled snippets using the
class-generator completion variable, one for bash_source and one for zsh_source,
so the instructions match the referenced shells.
- Around line 441-452: Update the Execution Order documentation to explicitly
state that --generate-missing short-circuits normal generation, so the CLI
returns before -k/--kind and --add-tests are processed; adjust the ordering note
in the class-generator CLI docs to make it clear these options are ignored in
the same invocation when --generate-missing is set.
In `@docs/common-patterns.md`:
- Around line 1-19: The published docs currently include internal generation
chatter from the documentation draft, so remove the “Let me…” transcript text
from the content used by the docs page. Update the doc source handling around
the page content in docs/common-patterns.md so only the actual documentation
remains, then regenerate the HTML artifacts to confirm the transcript no longer
renders.
In `@docs/connecting-to-clusters.md`:
- Around line 192-199: The in-cluster fallback description in get_client() is
too broad; it should only mention falling back after DynamicClient(...) raises
MaxRetryError, not after any kubeconfig/config-loading failure. Update the prose
around get_client() to narrow the claim, and keep the wording aligned with the
actual retry/fallback path used by the client initialization logic.
- Around line 267-307: Update the `get_client()` API reference so the return
type reflects both real and fake clients: the `get_client` signature/returns
section currently mentions only `DynamicClient`, but `fake=True` returns
`FakeDynamicClient` as well. Adjust the type description in the `get_client`
docs to include `FakeDynamicClient` alongside `DynamicClient`, and make sure the
parameter table entry for `fake` still points readers to that behavior.
In `@docs/creating-and-managing-resources.md`:
- Around line 447-455: The example snippet is missing the Namespace symbol used
in ResourceList(...), so add the appropriate Namespace import alongside the
existing ocp_resources imports in the documented example. Update the import
section near the ResourceList usage so Namespace is explicitly available before
constructing namespaces, keeping the example consistent with the other imported
resource types.
In `@docs/editing-resources-temporarily.md`:
- Around line 190-198: The no-op detection wording in ResourceEditor is too
broad and should be limited to the backup-enabled flow only. Update the
documentation around ResourceEditor’s no-op handling to clarify that unchanged
patches are skipped only when update(backup_resources=True) or the backup
context manager is used, while plain update() still applies the patch. Keep the
example message tied to the ResourceEdit skip behavior, and adjust the
surrounding text in the no-op detection section to match that scope.
In `@docs/error-handling.md`:
- Around line 477-489: The auth example disables TLS verification via the
Configuration setup, which is unsafe to copy into real usage. Update the snippet
around client_configuration_with_basic_auth and Configuration to avoid setting
verify_ssl to False, and instead show a trusted-CA/certificate-based
configuration or clearly mark the example as test-only. Keep the example focused
on secure auth flow and use the existing kubernetes.client.Configuration and
client_configuration_with_basic_auth symbols to locate the change.
In `@docs/managing-resource-lists.md`:
- Around line 182-190: The ResourceList example shows clean_up(wait=True) and
clean_up(wait=False) back-to-back, which makes it look like two sequential
teardowns on the same object. Update the snippet around ResourceList.deploy and
clean_up so the wait=True and wait=False calls are presented as mutually
exclusive alternatives, such as separate examples or an explicit either/or
structure, rather than consecutive commands.
In `@docs/pod-execution-and-logs.md`:
- Around line 1-12: Remove the AI scratch commentary from the published
documentation so the page starts with the actual pod execution and logs content.
Clean up the introductory block in the doc content before the real
title/sections begin, ensuring only finished documentation text remains and none
of the “Let me explore…/Now let me check…” notes are included.
In `@docs/querying-resources.md`:
- Around line 402-423: The field-selector examples use inconsistent syntax, so
update the snippets and nearby troubleshooting text to use one Kubernetes
field-selector form consistently. Review the `pod.events(...)` and
`Event.list(...)` examples in the querying-resources docs and replace the mixed
`==` usage with the standard syntax used by the wrapper’s `field_selector`
parameter, keeping the examples aligned throughout.
---
Outside diff comments:
In `@docs/quickstart.md`:
- Around line 466-474: The quickstart example is calling cm.create() redundantly
inside the ConfigMap context manager, which can double-submit the request.
Update the ConfigMap usage so the with ConfigMap(...) as cm: block relies on the
context manager’s built-in create/cleanup behavior, and remove the extra
create() call unless the fake-client path truly needs special handling. If it
does, make that exception explicit in the example near ConfigMap.
---
Duplicate comments:
In `@docs/pod-execution-and-logs.html`:
- Around line 269-274: The HTML output contains leaked AI scratch notes that
should not be rendered; remove the commentary from the source documentation and
regenerate the page. Update the `docs/pod-execution-and-logs.md` content that
feeds this HTML, then rebuild so the rendered output no longer includes the
exploratory sentences in the affected section.
---
Nitpick comments:
In @.gitleaks.toml:
- Line 7: The gitleaks allowlist is too broad because the docs/ entry in the
paths list excludes every file under docs/ from scanning. Narrow the exclusion
in .gitleaks.toml so only the generated placeholder-token docs are skipped,
using a more specific path/pattern near the existing class_generator/schema/
rule, and preserve scanning for authored docs assets such as markdown and JS.
In @.pre-commit-config.yaml:
- Line 45: The detect-secrets exclude in the pre-commit config is too broad and
disables scanning for the whole docs tree. Narrow the pattern in the pre-commit
hook configuration so it only skips the specific generated pages or
placeholder-token files, not every path under docs/; keep the change localized
in the hook entry that currently uses the docs/.* exclusion.
In `@docs/assets/style.css`:
- Around line 70-71: The mixed-case font-family values in the style sheet are
being flagged by the value-keyword-case lint rule, but the identifiers in the
font stack should remain unchanged. Update the Stylelint configuration to ignore
font-family for value-keyword-case, or add a targeted disable around the
relevant --font-sans and --font-mono declarations, rather than lowercasing the
font names themselves.
In `@docs/mcp-server-integration.md`:
- Line 94: Several fenced prompt-example blocks in the MCP server integration
docs are missing a language tag and are failing MD040. Update the affected
fenced code blocks in the markdown so they use a language identifier such as
text, keeping the existing prompt content intact and ensuring consistency with
Docsify syntax highlighting. Focus on the prompt-example fences throughout the
document rather than changing the surrounding prose.
In `@README.md`:
- Around line 3-4: The README now has multiple documentation pointers that
conflict, so consolidate them into a single canonical source or clearly label
one as primary and the others as secondary. Update the top-level docs link and
the existing “Docs:” reference plus the “## docs” section so they all point to
the same authoritative destination, and use consistent wording in README.md to
remove ambiguity for readers.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 297a7e88-3f1e-40f0-b0ea-201ece7de540
📒 Files selected for processing (58)
.gitleaks.toml.pre-commit-config.yamlREADME.mddocs/.nojekylldocs/assets/callouts.jsdocs/assets/codelabels.jsdocs/assets/copy.jsdocs/assets/github.jsdocs/assets/scrollspy.jsdocs/assets/search.jsdocs/assets/style.cssdocs/assets/theme.jsdocs/class-generator-cli.htmldocs/class-generator-cli.mddocs/common-patterns.htmldocs/common-patterns.mddocs/connecting-to-clusters.htmldocs/connecting-to-clusters.mddocs/creating-and-managing-resources.htmldocs/creating-and-managing-resources.mddocs/editing-resources-temporarily.htmldocs/editing-resources-temporarily.mddocs/environment-variables.htmldocs/environment-variables.mddocs/error-handling.htmldocs/error-handling.mddocs/generating-resource-classes.htmldocs/generating-resource-classes.mddocs/index.htmldocs/llms-full.txtdocs/llms.txtdocs/managing-resource-lists.htmldocs/managing-resource-lists.mddocs/mcp-server-integration.htmldocs/mcp-server-integration.mddocs/pod-execution-and-logs.htmldocs/pod-execution-and-logs.mddocs/querying-resources.htmldocs/querying-resources.mddocs/quickstart.htmldocs/quickstart.mddocs/resource-api.htmldocs/resource-api.mddocs/resource-class-hierarchy.htmldocs/resource-class-hierarchy.mddocs/schema-validation-internals.htmldocs/schema-validation-internals.mddocs/search-index.jsondocs/testing-without-cluster.htmldocs/testing-without-cluster.mddocs/validating-resources.htmldocs/validating-resources.mddocs/waiting-for-conditions.htmldocs/waiting-for-conditions.mddocs/working-with-events.htmldocs/working-with-events.mddocs/working-with-virtual-machines.htmldocs/working-with-virtual-machines.md
Comment on lines
+25
to
+28
| > **Tip:** Enable shell completion by adding to `~/.bashrc` or `~/.zshrc`: | ||
| > ```bash | ||
| > if type class-generator > /dev/null; then eval "$(_CLASS_GENERATOR_COMPLETE=zsh_source class-generator)"; fi | ||
| > ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Show separate bash and zsh completion snippets.
The snippet says it applies to both ~/.bashrc and ~/.zshrc, but it hard-codes zsh_source, so the bash example is wrong.
Proposed fix
-> ```bash
-> if type class-generator > /dev/null; then eval "$(_CLASS_GENERATOR_COMPLETE=zsh_source class-generator)"; fi
-> ```
+> ```bash
+> # bash
+> if type class-generator >/dev/null; then eval "$(_CLASS_GENERATOR_COMPLETE=bash_source class-generator)"; fi
+>
+> # zsh
+> if type class-generator >/dev/null; then eval "$(_CLASS_GENERATOR_COMPLETE=zsh_source class-generator)"; fi
+> ```📝 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.
Suggested change
| > **Tip:** Enable shell completion by adding to `~/.bashrc` or `~/.zshrc`: | |
| > ```bash | |
| > if type class-generator > /dev/null; then eval "$(_CLASS_GENERATOR_COMPLETE=zsh_source class-generator)"; fi | |
| > ``` | |
| > **Tip:** Enable shell completion by adding to `~/.bashrc` or `~/.zshrc`: | |
| > |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/class-generator-cli.md` around lines 25 - 28, The shell completion tip
currently mixes bash and zsh in one snippet and hard-codes zsh_source, so update
the docs to provide separate completion examples for bash and zsh. In the
class-generator-cli.md content, replace the single command with two clearly
labeled snippets using the class-generator completion variable, one for
bash_source and one for zsh_source, so the instructions match the referenced
shells.
Comment on lines
+441
to
+452
| ## Execution Order | ||
|
|
||
| When multiple compatible options are specified together, the CLI processes them in this fixed order: | ||
|
|
||
| 1. `--update-schema-for` (exits after completion) | ||
| 2. `--update-schema` (exits unless `--generate-missing` is also set) | ||
| 3. `--coverage-report` / `--discover-missing` / `--generate-missing` (coverage analysis and reporting) | ||
| 4. `--generate-missing` (generates classes for missing resources) | ||
| 5. `--regenerate-all` (batch regeneration, exits after completion) | ||
| 6. `-k`/`--kind` (normal kind generation) | ||
| 7. `--add-tests` (test generation and execution) | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Map the likely files first.
git ls-files | rg '^(class_generator/cli\.py|class_generator/tests/test_cli\.py|docs/class-generator-cli\.md)$'
printf '\n--- cli outline ---\n'
ast-grep outline class_generator/cli.py --view expanded || true
printf '\n--- test outline ---\n'
ast-grep outline class_generator/tests/test_cli.py --view expanded || true
printf '\n--- doc lines around target ---\n'
wc -l docs/class-generator-cli.md
sed -n '430,465p' docs/class-generator-cli.mdRepository: RedHatQE/openshift-python-wrapper
Length of output: 3256
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the execution branch handling around generate_missing and later options.
rg -n "generate[_-]missing|add_tests|kind|update_schema|coverage_report|discover_missing|regenerate_all" class_generator/cli.py class_generator/tests/test_cli.py
printf '\n--- relevant cli slice ---\n'
python3 - <<'PY'
from pathlib import Path
p = Path('class_generator/cli.py')
lines = p.read_text().splitlines()
for start, end in [(1, 260), (260, 520)]:
print(f"\n### {p} {start}-{end}")
for i in range(start, min(end, len(lines)) + 1):
print(f"{i:4d}: {lines[i-1]}")
PYRepository: RedHatQE/openshift-python-wrapper
Length of output: 37309
Document that --generate-missing exits before --kind / --add-tests. In the Execution Order section, note that --generate-missing returns before normal generation, so -k and --add-tests are ignored in the same invocation.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/class-generator-cli.md` around lines 441 - 452, Update the Execution
Order documentation to explicitly state that --generate-missing short-circuits
normal generation, so the CLI returns before -k/--kind and --add-tests are
processed; adjust the ordering note in the class-generator CLI docs to make it
clear these options are ignored in the same invocation when --generate-missing
is set.
Comment on lines
+663
to
+669
| The CLI manages two schema files under `class_generator/schema/`: | ||
|
|
||
| | File | Purpose | | ||
| |------|---------| | ||
| | `__resources-mappings.json.gz` | Compressed JSON mapping of lowercase Kind → list of schemas with GVK metadata and namespaced status | | ||
| | `_definitions.json` | JSON Schema definitions for `$ref` resolution during validation | | ||
| | `__cluster_version__.txt` | Last cluster version used for schema generation | |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Fix the schema-files count.
This section says the CLI manages two schema files, but the table lists three (__resources-mappings.json.gz, _definitions.json, and __cluster_version__.txt). Please make the intro and table agree.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/class-generator-cli.md` around lines 663 - 669, The schema-files summary
in the CLI docs is inconsistent with the table contents. Update the introductory
sentence around the schema file list so it matches the three entries shown, and
make sure the description around the schema management section stays aligned
with the symbols named in the table (`__resources-mappings.json.gz`,
`_definitions.json`, and `__cluster_version__.txt`).
Comment on lines
+1
to
+19
| Let me start by reading the knowledge graph and the pages manifest, then explore the codebase. | ||
|
|
||
| Now let me look at more resource files for networking, RBAC, and DataVolume: | ||
|
|
||
| Now let me look at the secret, network policy, network attachment definition, and the duplicate API groups handling: | ||
|
|
||
| Now let me look at the duplicate API groups handling: | ||
|
|
||
| Now let me look at some files with duplicate kinds to understand the pattern: | ||
|
|
||
| Now let me look at how to exec in pods and also look at the user_defined_network and apply_yaml approach: | ||
|
|
||
| Now let me look at how the `yaml_file` parameter works and look at the event-related code: | ||
|
|
||
| Now let me check some gateway files to see the pattern for duplicate API groups: | ||
|
|
||
| Now let me look at the `user_defined_network.py` for newer networking resources: | ||
|
|
||
| Now I have enough information. Let me write the documentation page: |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Remove the generation transcript from the published docs.
These Let me... notes are internal build chatter, not page content, and they will render verbatim. Strip them before publishing and regenerate the HTML artifacts.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/common-patterns.md` around lines 1 - 19, The published docs currently
include internal generation chatter from the documentation draft, so remove the
“Let me…” transcript text from the content used by the docs page. Update the doc
source handling around the page content in docs/common-patterns.md so only the
actual documentation remains, then regenerate the HTML artifacts to confirm the
transcript no longer renders.
Comment on lines
+192
to
+199
| When your code runs inside a pod on the cluster (for example, in a CI/CD pipeline or operator), `get_client()` automatically falls back to in-cluster configuration if the kubeconfig-based connection fails: | ||
|
|
||
| ```python | ||
| # Inside a pod — no config_file or host needed | ||
| client = get_client() | ||
| ``` | ||
|
|
||
| The library first attempts to connect using the kubeconfig. If that fails with a connection error, it loads credentials from the pod's service account token mounted at `/var/run/secrets/kubernetes.io/serviceaccount/`. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Narrow the in-cluster fallback claim.
get_client() only reaches in-cluster config after DynamicClient(...) raises MaxRetryError; earlier kubeconfig/config-loading failures won't follow this path.
Suggested wording
-`get_client()` automatically falls back to in-cluster configuration if the kubeconfig-based connection fails
+`get_client()` falls back to in-cluster configuration after client creation raises `MaxRetryError`📝 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.
Suggested change
| When your code runs inside a pod on the cluster (for example, in a CI/CD pipeline or operator), `get_client()` automatically falls back to in-cluster configuration if the kubeconfig-based connection fails: | |
| ```python | |
| # Inside a pod — no config_file or host needed | |
| client = get_client() | |
| ``` | |
| The library first attempts to connect using the kubeconfig. If that fails with a connection error, it loads credentials from the pod's service account token mounted at `/var/run/secrets/kubernetes.io/serviceaccount/`. | |
| When your code runs inside a pod on the cluster (for example, in a CI/CD pipeline or operator), `get_client()` falls back to in-cluster configuration after client creation raises `MaxRetryError`: | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/connecting-to-clusters.md` around lines 192 - 199, The in-cluster
fallback description in get_client() is too broad; it should only mention
falling back after DynamicClient(...) raises MaxRetryError, not after any
kubeconfig/config-loading failure. Update the prose around get_client() to
narrow the claim, and keep the wording aligned with the actual retry/fallback
path used by the client initialization logic.
Comment on lines
+243
to
+245
| ``` | ||
| {<Kind>: {<name>: <namespace>}} | ||
| ``` |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Tag this example fence with a language.
Markdownlint flags this bare fence (MD040). Since it contains a YAML dict example, mark it yaml.
Suggested fix
-```
+```yaml
{<Kind>: {<name>: <namespace>}}</details>
<!-- suggestion_start -->
<details>
<summary>📝 Committable suggestion</summary>
> ‼️ **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.
```suggestion
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 243-243: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
Source: Linters/SAST tools
Comment on lines
+477
to
+489
| configuration = kubernetes.client.Configuration() | ||
| configuration.verify_ssl = False | ||
|
|
||
| try: | ||
| api_client = client_configuration_with_basic_auth( | ||
| username="admin", | ||
| password="password", | ||
| host="https://api.cluster.example.com:6443", | ||
| configuration=configuration, | ||
| ) | ||
| except ClientWithBasicAuthError as e: | ||
| print(f"Authentication failed: {e}") | ||
| ``` |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Don't disable TLS verification in the auth example.
configuration.verify_ssl = False is easy to copy into real clusters and weakens the auth flow outside throwaway environments. Show a trusted-CA setup or label this snippet as test-only.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/error-handling.md` around lines 477 - 489, The auth example disables TLS
verification via the Configuration setup, which is unsafe to copy into real
usage. Update the snippet around client_configuration_with_basic_auth and
Configuration to avoid setting verify_ssl to False, and instead show a
trusted-CA/certificate-based configuration or clearly mark the example as
test-only. Keep the example focused on secure auth flow and use the existing
kubernetes.client.Configuration and client_configuration_with_basic_auth symbols
to locate the change.
Comment on lines
+182
to
+190
| Pass `wait=True` to `deploy()` to wait for each resource to reach a ready state. By default, `clean_up()` already waits for deletion to complete. | ||
|
|
||
| ```python | ||
| namespaces = ResourceList(resource_class=Namespace, num_resources=2, client=client, name="ns") | ||
| namespaces.deploy(wait=True) | ||
|
|
||
| # Later... | ||
| namespaces.clean_up(wait=True) # wait=True is the default | ||
| namespaces.clean_up(wait=False) # Skip waiting for deletion |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Show clean_up(wait=True) and clean_up(wait=False) as alternatives.
Written back-to-back, this reads like a second teardown pass on the same list. That is easy to copy incorrectly; make the two modes mutually exclusive in the example.
♻️ Suggested rewrite
namespaces.clean_up(wait=True) # wait=True is the default
-namespaces.clean_up(wait=False) # Skip waiting for deletion
+# Or, if you want to skip waiting:
+# namespaces.clean_up(wait=False)📝 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.
Suggested change
| Pass `wait=True` to `deploy()` to wait for each resource to reach a ready state. By default, `clean_up()` already waits for deletion to complete. | |
| ```python | |
| namespaces = ResourceList(resource_class=Namespace, num_resources=2, client=client, name="ns") | |
| namespaces.deploy(wait=True) | |
| # Later... | |
| namespaces.clean_up(wait=True) # wait=True is the default | |
| namespaces.clean_up(wait=False) # Skip waiting for deletion | |
| Pass `wait=True` to `deploy()` to wait for each resource to reach a ready state. By default, `clean_up()` already waits for deletion to complete. | |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/managing-resource-lists.md` around lines 182 - 190, The ResourceList
example shows clean_up(wait=True) and clean_up(wait=False) back-to-back, which
makes it look like two sequential teardowns on the same object. Update the
snippet around ResourceList.deploy and clean_up so the wait=True and wait=False
calls are presented as mutually exclusive alternatives, such as separate
examples or an explicit either/or structure, rather than consecutive commands.
Comment on lines
+1
to
+12
| Let me explore the repository structure and understand the codebase first. | ||
|
|
||
| Now let me check the `read_namespaced_pod_log` kwargs available, and look at how the MCP server uses log parameters: | ||
|
|
||
| Now let me check the import paths and verify the `get_client` function: | ||
|
|
||
| Now let me check test files for pod execution tests: | ||
|
|
||
| Now let me also verify whether the Node class has a `name` property: | ||
|
|
||
| Now I have all the information I need to write the documentation. Let me compose it: | ||
|
|
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟠 Major | ⚡ Quick win
Remove leaked AI-generation scratch notes from the published doc.
Lines 1-12 contain leftover generation-process commentary ("Let me explore the repository structure...", "Now let me check...") that isn't part of the actual documentation content. This reads as unpolished/broken to end users and should be stripped before the page's actual title/content begins at line 13.
Proposed fix
-Let me explore the repository structure and understand the codebase first.
-
-Now let me check the `read_namespaced_pod_log` kwargs available, and look at how the MCP server uses log parameters:
-
-Now let me check the import paths and verify the `get_client` function:
-
-Now let me check test files for pod execution tests:
-
-Now let me also verify whether the Node class has a `name` property:
-
-Now I have all the information I need to write the documentation. Let me compose it:
-
# Executing Commands in Pods and Retrieving Logs📝 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.
Suggested change
| Let me explore the repository structure and understand the codebase first. | |
| Now let me check the `read_namespaced_pod_log` kwargs available, and look at how the MCP server uses log parameters: | |
| Now let me check the import paths and verify the `get_client` function: | |
| Now let me check test files for pod execution tests: | |
| Now let me also verify whether the Node class has a `name` property: | |
| Now I have all the information I need to write the documentation. Let me compose it: | |
| # Executing Commands in Pods and Retrieving Logs |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/pod-execution-and-logs.md` around lines 1 - 12, Remove the AI scratch
commentary from the published documentation so the page starts with the actual
pod execution and logs content. Clean up the introductory block in the doc
content before the real title/sections begin, ensuring only finished
documentation text remains and none of the “Let me explore…/Now let me check…”
notes are included.
Comment on lines
+402
to
+423
| ```python | ||
| # Example: filter for Warning events with a specific reason | ||
| for event in pod.events( | ||
| field_selector="type==Warning,reason==BackOff", | ||
| timeout=10, | ||
| ): | ||
| print(event.object.message) | ||
| ``` | ||
|
|
||
| ### List existing events (non-streaming) | ||
|
|
||
| Use `Event.list()` to get a snapshot of existing events without streaming: | ||
|
|
||
| ```python | ||
| from ocp_resources.event import Event | ||
|
|
||
| # List Warning events from the last 5 minutes | ||
| events = Event.list( | ||
| client=client, | ||
| namespace="my-namespace", | ||
| field_selector="type==Warning", | ||
| ) |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Find all relevant field_selector mentions and implementation points.
rg -n --hidden --glob '!**/.git/**' \
'field_selector|field selector|field-selector|==Warning|reason==|status\.phase==|status.phase=' \
docs src . 2>/dev/null | sed -n '1,240p'
echo '--- FILE LIST ---'
git ls-files | rg '(^docs/|(^|/)event(\.|\b)|field_selector|selector|resource)' | sed -n '1,240p'Repository: RedHatQE/openshift-python-wrapper
Length of output: 50392
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect likely implementation files for selector handling.
files=$(git ls-files | rg '(^src/|^ocp_resources/|^lib/).*(event|selector|resource)')
printf '%s\n' "$files" | sed -n '1,200p'
# Map the most likely candidate(s) before reading.
for f in $files; do
case "$f" in
*event*|*selector*|*resource*)
echo "--- OUTLINE: $f ---"
ast-grep outline "$f" --view expanded 2>/dev/null || true
;;
esac
doneRepository: RedHatQE/openshift-python-wrapper
Length of output: 8281
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Read the relevant doc sections around the referenced lines.
for f in docs/querying-resources.md; do
echo "--- $f (around cited lines) ---"
sed -n '380,470p' "$f" | cat -n
echo "--- $f (later mention) ---"
sed -n '530,570p' "$f" | cat -n
doneRepository: RedHatQE/openshift-python-wrapper
Length of output: 4808
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the implementation that builds/passes field selectors.
sed -n '1180,1465p' ocp_resources/resource.py | cat -n
echo '---'
sed -n '1,240p' ocp_resources/event.py | cat -nRepository: RedHatQE/openshift-python-wrapper
Length of output: 23540
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the documentation source around the cited lines for the exact selector strings.
sed -n '400,470p' docs/querying-resources.md | cat -n
echo '---'
sed -n '540,565p' docs/querying-resources.md | cat -nRepository: RedHatQE/openshift-python-wrapper
Length of output: 3725
Normalize the field-selector syntax in these examples. The wrapper passes field_selector through unchanged, so the docs should use one Kubernetes field-selector form consistently instead of mixing == and = across the snippets and troubleshooting text.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/querying-resources.md` around lines 402 - 423, The field-selector
examples use inconsistent syntax, so update the snippets and nearby
troubleshooting text to use one Kubernetes field-selector form consistently.
Review the `pod.events(...)` and `Event.list(...)` examples in the
querying-resources docs and replace the mixed `==` usage with the standard
syntax used by the wrapper’s `field_selector` parameter, keeping the examples
aligned throughout.
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
4 participants
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.
Generated with docsfy using claude/claude-opus-4-6-1m
Changes:
Summary by CodeRabbit
New Features
Documentation