7f5dd7e5be
updated template for mkdocs and rendered MCP docs and site
2026-03-07 16:07:18 +05:30
17d39a3e88
updated doc strings
2026-03-07 15:44:02 +05:30
219d6f9f87
google styled doc string and create README.md using package doc string
2026-02-28 19:56:58 +05:30
22fceef020
Flatten MkDocs Structure + --module-is-source Support ( #4 )
...
# Merge Request: Flatten MkDocs Structure + `--module-is-source` Support
## Summary
This MR introduces structural improvements to the MkDocs generation pipeline to:
1. Ensure a root `docs/index.md` always exists
2. Flatten documentation structure (remove `docs/<module>/` nesting by default)
3. Add support for `--module-is-source` to treat the module as the documentation root
4. Align navigation (`docforge.nav.yml`) with the new flat layout
5. Regenerate MCP artifacts to reflect updated signatures and docstrings
This resolves static hosting issues (e.g., Nginx 403 due to missing `site/index.html`) and makes each generated MkDocs site deployable as a standalone static website.
---
## Motivation
Previously, documentation was generated under:
```
docs/<module>/...
```
Which resulted in:
```
site/<module>/index.html
```
When deployed at `/libs/<project>/`, this caused:
* Missing `site/index.html`
* Nginx returning 403 for root access
* Inconsistent static hosting behavior
This MR corrects the architecture so each MkDocs build is a valid static site with a root entry point.
---
## Key Changes
### 1️⃣ Flattened Docs Structure
**Before**
```
docs/docforge/index.md
```
**After**
```
docs/index.md
```
All documentation paths were updated accordingly:
* `docs/docforge/cli/...` → `docs/cli/...`
* `docs/docforge/models/...` → `docs/models/...`
* `docs/docforge/renderers/...` → `docs/renderers/...`
Navigation updated to match the flat layout.
---
### 2️⃣ Root Index Enforcement
`MkDocsRenderer` now guarantees:
* `docs/index.md` is always created
* Parent `index.md` files are auto-generated if missing
* Parent indexes link to child modules (idempotent behavior)
This ensures:
```
site/index.html
```
Always exists after `mkdocs build`.
---
### 3️⃣ New CLI Flag: `--module-is-source`
Added option:
```
--module-is-source
```
Behavior:
* Treats the provided module as the documentation root
* Removes the top-level module folder from generated paths
* Prevents redundant nesting when the module corresponds to the source root
Updated components:
* `cli.commands.build`
* `mkdocs_utils.generate_sources`
* `MkDocsRenderer.generate_sources`
* Stub files (`.pyi`)
* MCP JSON artifacts
---
### 4️⃣ Navigation Spec Update
`docforge.nav.yml` updated:
**Before**
```yaml
home: docforge/index.md
```
**After**
```yaml
home: index.md
```
All group paths adjusted to remove `docforge/` prefix.
---
### 5️⃣ MkDocs Config Update
`mkdocs.yml` updated to:
* Move `site_name` below theme/plugins
* Use flat navigation paths
* Point Home to `index.md`
---
### 6️⃣ MCP Artifact Regeneration
Updated:
* Function signatures (new parameter)
* Docstrings (reflect `module_is_source`)
* Renderer metadata
* Line numbers
Ensures MCP output matches updated API.
---
## Architectural Outcome
Each project now produces a **valid standalone static site**:
```
site/
index.html
assets/
search/
```
Safe for deployment under:
```
/libs/<project>/
```
No Nginx rewrites required.
No directory-index issues.
No nested-site ambiguity.
---
## Backward Compatibility
* Existing CLI usage remains valid
* `--module-is-source` is optional
* Navigation spec format unchanged (only paths adjusted)
---
## Deployment Impact
After merge:
* Each library can be deployed independently
* Sites can be merged under a shared root without internal conflicts
* Static hosting is predictable and production-safe
---
## Testing
* Verified MkDocs build produces `site/index.html`
* Verified navigation renders correctly
* Verified parent index generation is idempotent
* Regenerated MCP docs and validated schema consistency
---
## Result
The documentation compiler now:
* Produces structurally correct static sites
* Supports flat and source-root modes
* Eliminates 403 root issues
* Scales cleanly across multiple repositories
This aligns doc-forge with proper static-site architectural invariants.
Reviewed-on: #4
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com >
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com >
2026-02-21 16:16:36 +00:00
ff92906720
cli-cleanup ( #2 )
...
continuous-integration/drone/tag Build was killed
Reviewed-on: #2
Co-authored-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com >
Co-committed-by: Vishesh 'ironeagle' Bangotra <aetoskia@gmail.com >
2026-01-21 13:25:57 +00:00
ef378e676b
doc:// instead of mcp://
2026-01-21 17:10:09 +05:30
5370a7faa2
feat(mcp): add MCP JSON renderer and CLI support, update tests accordingly
...
- Add MCPRenderer to generate MCP-native JSON bundles (index.json, nav.json, modules/*.json)
- Expose MCPRenderer via public API and CLI (`generate-mcp` command)
- Replace Markdown-based MCP output with structured JSON resources
- Update MCP renderer type stubs to match new JSON-based implementation
- Refactor MCP tests to validate JSON content, bundle structure, and navigation
- Fix MCP module coverage test to use explicit project_root for reliable discovery
2026-01-21 16:43:21 +05:30
427e407d26
added mcp_renderer
2026-01-21 16:18:25 +05:30
9a5e356039
rename mkdocs.py to mkdocs_renderer.py
2026-01-21 16:04:02 +05:30
4a876abc62
refactor: rename loader/model packages to loaders/models
...
- Rename docforge.loader → docforge.loaders and docforge.model → docforge.models
- Update all imports, type stubs, CLI, tests, and documentation references
- Align MkDocs navigation and docforge.nav.yml with new package structure
- Adjust module docstrings and comments for consistency with pluralized naming
2026-01-21 15:45:48 +05:30
b6e5114532
added docs strings
continuous-integration/drone/tag Build is passing
2026-01-21 01:00:12 +05:30
6b334fd181
removed future anotations
2026-01-20 23:35:41 +05:30
dca19caaf3
fix: make MkDocs generation filesystem-complete and package-aware
...
- Add filesystem-based module discovery via `discover_module_paths`
- Decouple documentation coverage from Python import behavior
- Ensure GriffeLoader receives a full module list instead of a single root
- Make MkDocs renderer level-agnostic using global package detection
- Emit `index.md` only for true packages, suppress `<package>.md`
- Mirror full dotted module hierarchy into nested docs directories
- Update CLI, exports, and type stubs to expose discovery helper
- Align tests with filesystem-driven module coverage
This fixes missing docs for submodules and removes invalid package `.md` files.
2026-01-20 23:25:56 +05:30
778a986262
.pyi fixes
2026-01-20 20:50:59 +05:30
7c027834c0
fixes
2026-01-20 20:37:46 +05:30
65eb1b9fe8
rendered MkDocs
2026-01-20 20:25:46 +05:30
c910da9d14
cleanup code
2026-01-20 18:39:12 +05:30
a45725160d
init docforge lib
2026-01-20 18:22:16 +05:30
