docs: start restructuring and add local build automation #1528
Conversation
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
Contributor
Greptile OverviewGreptile SummaryThis PR adds local documentation build automation and begins restructuring the documentation organization. The changes include new build scripts ( Key improvements:
Issues found:
|
| Filename | Score | Overview |
|---|---|---|
| Makefile | 5/5 | Added docs-serve target to enable live documentation server with auto-rebuild functionality, along with corresponding help text |
| docs/serve.py | 5/5 | New Python script to run sphinx-autobuild with configurable port, host, and browser options, includes proper error handling |
| pyproject.toml | 5/5 | Added sphinx-design and sphinx-autobuild dependencies to the docs group for enhanced documentation features and live server |
| docs/index.md | 3/5 | Restructured main documentation page with new organization, removed old content inclusion, added placeholder "TBD" text, moved getting-started.md to tutorials section |
| docs/overview.md | 2/5 | New comprehensive overview with use cases and benefits, but contains broken references to deleted getting-started.md file |
| docs/how-it-works.md | 4/5 | New landing page with card-based navigation to guardrails process and architecture guides, includes repetitive introductory text |
Sequence Diagram
sequenceDiagram
participant Dev as Developer
participant Make as Makefile
participant Script as serve.py/serve.sh
participant Sphinx as sphinx-autobuild
participant Browser as Web Browser
Dev->>Make: make docs-serve
Make->>Script: cd docs && run sphinx-autobuild
Script->>Sphinx: Start with config (port 8000, watch patterns)
Sphinx->>Sphinx: Initial build from source
Sphinx->>Browser: Open http://127.0.0.1:8000
Browser->>Dev: Display documentation
loop Live Development
Dev->>Sphinx: Save .md, .rst, or .py file
Sphinx->>Sphinx: Detect change (1s debounce)
Sphinx->>Sphinx: Rebuild affected pages
Sphinx->>Browser: Push update via WebSocket
Browser->>Browser: Auto-refresh with new content
end
Dev->>Sphinx: Ctrl+C
Sphinx->>Make: Server stopped
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
docs/overview.md
Outdated
|
|
||
| The input and output format for the `generate` method is similar to the [Chat Completions API](https://platform.openai.com/docs/guides/gpt/chat-completions-api) from OpenAI. | ||
|
|
||
| For more information, refer to the [Python API Guide](user-guides/python-api.md) and [Getting Started](getting-started.md). |
Contributor
There was a problem hiding this comment.
logic: Broken link - getting-started.md was deleted in this PR but is still referenced here
Suggested change
| For more information, refer to the [Python API Guide](user-guides/python-api.md) and [Getting Started](getting-started.md). | |
| For more information, refer to the [Python API Guide](user-guides/python-api.md) and [Installation Guide](getting-started/installation-guide.md). |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/overview.md
Line: 70:70
Comment:
**logic:** Broken link - `getting-started.md` was deleted in this PR but is still referenced here
```suggestion
For more information, refer to the [Python API Guide](user-guides/python-api.md) and [Installation Guide](getting-started/installation-guide.md).
```
How can I resolve this? If you propose a fix, please make it concise.
docs/overview.md
Outdated
| - **Community models**: Support for [LlamaGuard](user-guides/community/llama-guard.md), [Fiddler Guardrails](user-guides/community/fiddler.md), and other content safety solutions. | ||
| - **Third-party APIs**: Integration with [ActiveFence](user-guides/guardrails-library.md#activefence), [Cisco AI Defense](user-guides/community/ai-defense.md), and other moderation services. | ||
|
|
||
| For more information, refer to the [Content Safety section](user-guides/guardrails-library.md#content-safety) in the Guardrails Library and the [Getting Started guide](getting-started.md). |
Contributor
There was a problem hiding this comment.
logic: Broken link - getting-started.md was deleted in this PR but is still referenced here
Suggested change
| For more information, refer to the [Content Safety section](user-guides/guardrails-library.md#content-safety) in the Guardrails Library and the [Getting Started guide](getting-started.md). | |
| For more information, refer to the [Content Safety section](user-guides/guardrails-library.md#content-safety) in the Guardrails Library. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/overview.md
Line: 114:114
Comment:
**logic:** Broken link - `getting-started.md` was deleted in this PR but is still referenced here
```suggestion
For more information, refer to the [Content Safety section](user-guides/guardrails-library.md#content-safety) in the Guardrails Library.
```
How can I resolve this? If you propose a fix, please make it concise.
docs/about/how-it-works.md
Outdated
Comment on lines
1
to
3
| # How It Works | ||
|
|
||
| NeMo Guardrails is a toolkit for building guardrails for your LLM applications. It provides a set of tools and libraries for building guardrails for your LLM applications. It works by using a set of tools and libraries to build guardrails for your LLM applications. |
Contributor
There was a problem hiding this comment.
style: Repetitive text - same phrase appears three times in a row
Suggested change
| # How It Works | |
| NeMo Guardrails is a toolkit for building guardrails for your LLM applications. It provides a set of tools and libraries for building guardrails for your LLM applications. It works by using a set of tools and libraries to build guardrails for your LLM applications. | |
| # How It Works | |
| NeMo Guardrails is a toolkit for building guardrails for your LLM applications. It provides a set of tools and libraries that work together to protect and control LLM behavior. |
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/how-it-works.md
Line: 1:3
Comment:
**style:** Repetitive text - same phrase appears three times in a row
```suggestion
# How It Works
NeMo Guardrails is a toolkit for building guardrails for your LLM applications. It provides a set of tools and libraries that work together to protect and control LLM behavior.
```
How can I resolve this? If you propose a fix, please make it concise.
docs/index.md
Outdated
| ```{include} ../README.md | ||
| :start-after: <!-- start-documentation-reuse --> | ||
| :end-before: <!-- end-documentation-reuse -- | ||
| TBD |
Contributor
There was a problem hiding this comment.
style: Placeholder "TBD" should be replaced with actual welcome text
Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/index.md
Line: 8:8
Comment:
**style:** Placeholder "TBD" should be replaced with actual welcome text
How can I resolve this? If you propose a fix, please make it concise.
Contributor
Documentation preview |
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
miyoungc
force-pushed
the
doc-restructuring
branch
from
fff2055 to
bd11671
Compare
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.
Description
Related Issue(s)
Checklist