feat(documentation)📝: Add guided tutorial for llamabot docs write command

- Create a new documentation file for the LlamaBot CLI.
- Include usage instructions and options for `llamabot docs write`.
- Provide information on the `--force` flag usage.
- Explain requirements for target documentation file formatting and placement.
- Detail necessary frontmatter key-value pairs for the command.

Author: ericmjl

docs/cli/docs.md

@@ -0,0 +1,74 @@
+---
+intents:
+- Provide reader with a guided tutorial that shows how to use the `llamabot docs write`
+  command at the terminal to generate documentation.
+- Specifically add in information about the `--force` flag.
+- Describe the frontmatter key-value pairs needed to make it work.
+linked_files:
+- llamabot/cli/docs.py
+- pyproject.toml
+---
+
+# LlamaBot Documentation
+
+## Installation
+
+To install LlamaBot, follow these steps:
+
+1. Ensure you have Python 3.10 or higher installed on your system.
+2. Install LlamaBot using pip:
+
+```bash
+pip install llamabot
+```
+
+3. Verify the installation by running:
+
+```bash
+llamabot --help
+```
+
+## Usage
+
+To use LlamaBot to generate documentation, run the following command in the terminal:
+
+```bash
+llamabot docs write <path_to_markdown_file>
+```
+
+### Options
+
+- `--force`: Use this flag to force the documentation update even if it is not detected as out of date.
+
+## Additional Information
+
+For more information, refer to the [official documentation](https://llamabotdocs.com).
+
+## Explanation
+
+To make the `llamabot docs write` command work, ensure that your Markdown source files are properly formatted and located in the correct directory. The command will read the source files, check if the documentation is up-to-date, and update it if necessary. If you use the `--force` flag, the documentation will be updated regardless of its current status.
+
+### Requirements for Target Documentation File
+
+1. **Proper Formatting**: Ensure your Markdown files are correctly formatted.
+2. **Correct Directory**: Place your Markdown files in the appropriate directory as expected by the `llamabot docs write` command.
+3. **Linked Files**: If your documentation references other files, ensure these are correctly linked and accessible.
+
+### Frontmatter Key-Value Pairs
+
+To use the `llamabot docs write` command effectively, your Markdown files should include the following frontmatter:
+
+```markdown
+---
+intents:
+- Point 1 that the documentation should cover.
+- Point 2 that the documentation should cover.
+- ...
+linked_files:
+- path/to/relevant_file1.py
+- path/to/relevant_file2.toml
+- ...
+---
+```
+
+By following these guidelines, you can effectively use LlamaBot to manage and update your documentation.

llamabot/cli/docs.py

@@ -3,12 +3,13 @@
 from typer import Typer
 from pathlib import Path
 import frontmatter
-from pydantic import BaseModel, Field
-from llamabot import prompt, StructuredBot, SimpleBot
+from pydantic import BaseModel, Field, model_validator
+from llamabot import prompt, StructuredBot
 from pyprojroot import here
 
 from pydantic import ConfigDict
 
+
 app = Typer()
 
 
@@ -47,6 +48,21 @@ def save(self):
             f.write(frontmatter.dumps(self.post))
 
 
+class DocumentationContent(BaseModel):
+    """Content related to documentation."""
+
+    content: str = Field(..., description="The documentation content.")
+
+    @model_validator(mode="after")
+    def check_content(self):
+        """Validate the content field."""
+        if self.content.startswith("```") or self.content.endswith("```"):
+            raise ValueError(
+                "Documentation content should not start or end with triple backticks."
+            )
+        return self
+
+
 class DocumentationOutOfDate(BaseModel):
     """Status indicating whether a documentation is out of date."""
 
@@ -56,7 +72,7 @@ class DocumentationOutOfDate(BaseModel):
 
 
 @prompt
-def ood_checker_sysprompt():
+def ood_checker_sysprompt() -> str:
     """You are an expert in documentation management.
     You will be provided information about a written documentation file,
     what the documentation is intended to convey,
@@ -67,7 +83,9 @@ def ood_checker_sysprompt():
 
 @prompt
 def documentation_information(source_file: MarkdownSourceFile) -> str:
-    """## Referenced source files
+    """Here, I will provide you with contextual information to do your work.
+
+    ## Referenced source files
 
     These are the source files to reference:
 
@@ -96,46 +114,68 @@ def documentation_information(source_file: MarkdownSourceFile) -> str:
     Here is the intent about the documentation:
 
     {% for intent in source_file.post.get("intents", []) %}- {{ intent }}{% endfor %}
+    -----
     """
 
 
 @prompt
 def docwriter_sysprompt():
-    """You are an expert in documentation writing.
+    """
+    [[ Persona ]]
+    You are an expert in documentation writing.
 
+    [[ Context ]]
     You will be provided a documentation source,
     a list of what the documentation is intended to cover,
     and a list of linked source files.
 
+    [[ Instructions ]]
     Based on the intended messages information that the documentation is supposed to cover
     and the content of linked source files,
     please edit or create the documentation,
     ensuring that the documentation matches the intents
     and has the correct content from the linked source files.
+    Return only the Markdown content of the documentation without the surrounding fence.
     """
 
 
 @app.command()
 def write(file_path: Path, force: bool = False):
     """Write the documentation based on the given source file.
 
+    The Markdown file should have frontmatter that looks like this:
+
+    ```markdown
+    ---
+    intents:
+    - Point 1 that the documentation should cover.
+    - Point 2 that the documentation should cover.
+    - ...
+    linked_files:
+    - path/to/relevant_file1.py
+    - path/to/relevant_file2.toml
+    - ...
+    ---
+    ```
+
     :param file_path: Path to the Markdown source file.
     :param force: Force writing the documentation even if it is not out of date.
     """
     src_file = MarkdownSourceFile(file_path)
 
-    if not src_file.post.content:  # i.e. the documentation is empty
-        docwriter = SimpleBot(system_prompt=docwriter_sysprompt())
-        response = docwriter(documentation_information(src_file))
-        src_file.post.content = response.content
+    docwriter = StructuredBot(
+        system_prompt=docwriter_sysprompt(),
+        pydantic_model=DocumentationContent,
+        model_name="gpt-4o",
+    )
+    ood_checker = StructuredBot(
+        system_prompt=ood_checker_sysprompt(), pydantic_model=DocumentationOutOfDate
+    )
+    result: DocumentationOutOfDate = ood_checker(documentation_information(src_file))
 
-    else:
-        ood_checker = StructuredBot(
-            system_prompt=ood_checker_sysprompt(), pydantic_model=DocumentationOutOfDate
+    if not src_file.post.content or result.is_out_of_date or force:
+        response: DocumentationContent = docwriter(
+            documentation_information(src_file) + "\nNow please write the docs."
         )
-        result = ood_checker(documentation_information(src_file))
-        if result.is_out_of_date or force:
-            docwriter = SimpleBot(system_prompt=docwriter_sysprompt())
-            response = docwriter(documentation_information(src_file))
-            src_file.post.content = response.content
+        src_file.post.content = response.content
     src_file.save()