Switch documentation to a combination of silverbullet-pub and mkdocs #71
Conversation
WalkthroughWalkthroughThe pull request encompasses a series of updates to documentation files associated with the AI Core Library. Key changes include the renaming of template references, the introduction of new commands and features, the addition of deprecation warnings for certain commands, and enhancements to the overall structure and formatting of documentation. Additionally, a new script was introduced to improve the MkDocs documentation generation process. Changes
Possibly related PRs
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
Outside diff range and nitpick comments (2)
docs/Commands/AI: Summarize Note and open summary.md (1)
6-8: Deprecation warning is clear and helpful.The deprecation warning is prominently placed and effectively communicates to users that they should transition to using "Templated Prompts" instead. This is a good practice to guide users towards the preferred approach.
To further enhance the documentation, consider the following suggestions:
Provide a brief explanation of why the command is being deprecated. This can help users understand the rationale behind the change.
Include a link to the documentation for "Templated Prompts" to make it easier for users to find information on the alternative approach.
If applicable, mention any migration steps or considerations users should be aware of when transitioning from this command to "Templated Prompts".
These additions can make the deprecation process smoother and more informative for users.
docs/Changelog.md (1)
76-76: Remove the empty line before the horizontal rule for consistency.To maintain consistency with the rest of the changelog entries, consider removing the empty line before the horizontal rule separating the entries. This will improve the readability of the changelog.
Apply this diff to remove the empty line:
- ---
Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Files ignored due to path filters (4)
.github/workflows/gh-pages-docs.ymlis excluded by none and included by none.gitignoreis excluded by none and included by nonemkdocs.ymlis excluded by none and included by nonerender-docs.shis excluded by none and included by none
Files selected for processing (17)
- docs/AI Core Library.md (2 hunks)
- docs/Changelog.md (2 hunks)
- docs/Commands/AI: Call OpenAI with Note as context.md (1 hunks)
- docs/Commands/AI: Generate Note FrontMatter.md (1 hunks)
- docs/Commands/AI: Insert Summary.md (1 hunks)
- docs/Commands/AI: Select Embedding Model from Config.md (1 hunks)
- docs/Commands/AI: Select Image Model from Config.md (1 hunks)
- docs/Commands/AI: Select Text Model from Config.md (1 hunks)
- docs/Commands/AI: Stream response with selection or note as prompt.md (1 hunks)
- docs/Commands/AI: Summarize Note and open summary.md (1 hunks)
- docs/Commands/AI: Test Embedding Generation.md (1 hunks)
- docs/Development.md (1 hunks)
- docs/Installation.md (1 hunks)
- docs/Library/AIDocs/Query/AI Template.md (1 hunks)
- docs/Quick Start.md (1 hunks)
- docs/Templated Prompts.md (1 hunks)
- docs/mkdocs-sb.py (1 hunks)
Files skipped from review due to trivial changes (8)
- docs/AI Core Library.md
- docs/Commands/AI: Select Embedding Model from Config.md
- docs/Commands/AI: Select Image Model from Config.md
- docs/Commands/AI: Select Text Model from Config.md
- docs/Commands/AI: Test Embedding Generation.md
- docs/Installation.md
- docs/Quick Start.md
- docs/Templated Prompts.md
Additional context used
Path-based instructions (8)
docs/Library/AIDocs/Query/AI Template.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Commands/AI: Stream response with selection or note as prompt.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Commands/AI: Insert Summary.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Commands/AI: Summarize Note and open summary.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Commands/AI: Call OpenAI with Note as context.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Commands/AI: Generate Note FrontMatter.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Development.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
docs/Changelog.md (1)
Pattern
**/*.md: Review these markdown files. They are written for a markdown note taking tool called Silverbullet, and may contain extra syntax not typically found in markdown.Ensure any documentation makes sense and is good.
LanguageTool
docs/Commands/AI: Generate Note FrontMatter.md
[style] ~8-~8: Consider using a shorter alternative to avoid wordiness.
Context: ...e submit feedback if you have ideas for making it better. This command will attempt to extract ...(MADE_IT_JJR)
docs/Development.md
[style] ~26-~26: Consider using a different verb to strengthen your wording.
Context: ...nd load the new version of the plug (or speed up this process by running the {[Sync: Now...(SPEED_UP_ACCELERATE)
Additional comments not posted (13)
docs/Library/AIDocs/Query/AI Template.md (1)
1-8: The AI documentation template looks great!The template provides a clear and consistent structure for documenting AI prompts and their associated details. The use of conditional rendering based on the presence of an
aipromptobject allows for flexibility in displaying either specific or general descriptions. Additionally, the optional usage information enhances the documentation's usability.Suggestions for further improvement:
- Consider adding more optional sections, such as examples or best practices, to provide additional context and guidance for using the AI prompts.
- If applicable, include a section for documenting any limitations or considerations when using the AI prompts.
Overall, the template is well-structured and will contribute to a more organized and informative AI documentation.
docs/Commands/AI: Stream response with selection or note as prompt.md (1)
5-7: LGTM!The deprecation warning is clear, well-placed, and provides an alternative command to use. This effectively communicates the deprecation and guides users to transition to the new recommended approach.
docs/Commands/AI: Insert Summary.md (1)
8-8: LGTM!The deprecation warning is clear, prominently placed, and provides an alternative for users. This effectively communicates the change in the command's status and guides users to the recommended approach.
docs/Commands/AI: Call OpenAI with Note as context.md (1)
9-9: The deprecation warning is clear and informative.The warning effectively communicates that the command is deprecated and should not be used. It also provides a clear alternative by directing users to use [[Templated Prompts]] instead.
The prominent placement of the warning using a blockquote and bold text ensures that users will notice the deprecation message.
docs/Commands/AI: Generate Note FrontMatter.md (1)
8-8: The changes improve the documentation.Formatting the experimental note as a block quote enhances its visibility and makes the documentation more readable. The documentation clearly explains the purpose of the command and provides instructions for adding additional rules. It also sets the right expectations about the LLM's behavior without specific prompt rules.
Great job on improving the documentation!
Tools
LanguageTool
[style] ~8-~8: Consider using a shorter alternative to avoid wordiness.
Context: ...e submit feedback if you have ideas for making it better. This command will attempt to extract ...(MADE_IT_JJR)
docs/Development.md (2)
26-26: LGTM!The segment provides a helpful tip to speed up the process of loading the new version of the plug. The current wording is clear and concise.
Tools
LanguageTool
[style] ~26-~26: Consider using a different verb to strengthen your wording.
Context: ...nd load the new version of the plug (or speed up this process by running the {[Sync: Now...(SPEED_UP_ACCELERATE)
29-42: Excellent documentation!The new documentation section provides clear and well-explained instructions for rendering documentation using silverbullet-pub and mkdocs. The instructions for making changes locally and seeing real-time updates are very helpful for developers working on the documentation. The mention of manually editing markdown files using any editor provides flexibility to developers.
Great job on enhancing the documentation process!
docs/mkdocs-sb.py (5)
10-14: LGTM!The function logic is correct, and the implementation is accurate. It effectively checks for the existence of the target Markdown file based on the provided link.
16-29: LGTM!The function logic is correct, and the implementation is accurate. It effectively processes the wiki link matches, finds the target files, and constructs the appropriate Markdown links.
31-34: LGTM!The function logic is correct, and the implementation is accurate. It effectively converts blockquotes with bold headers into MkDocs-style admonitions, improving the formatting and presentation of notes within the documentation.
36-39: LGTM!The function logic is correct, and the implementation is accurate. It effectively identifies and replaces wiki-style links in the Markdown text by invoking the
replace_wiki_linkfunction for each match.
41-45: LGTM!The event handler is implemented correctly. It effectively integrates the link processing and admonition conversion into the MkDocs page rendering process by modifying the Markdown content before it is rendered.
docs/Changelog.md (1)
32-32: Documentation website revamp looks good!The update to use mkdocs and mkdocs-material in addition to silverbullet-pub aligns with the PR objectives and seems to be a well-thought-out approach to enhance the documentation experience by improving the structure and presentation while still leveraging silverbullet-pub for specific functionalities.
UI stuff is not my strongsuit, and I'd rather not try making a full-fledged docs website. After looking at a few options, I settled on using mkdocs-material which looks pretty good imo.
Docs are now being rendered first by silverbullet-pub to render queries/templates, and then being processed by mkdocs (and mkdocs-material) to turn it into a prettier docs website.