Merge pull request #86 from raphael-francis/docs-launch

Docs launch

.gitignore

@@ -7,4 +7,6 @@ __pycache__/
 *.patch
 .ipynb_checkpoints
 
-.python-version
+.python-version
+
+!.vscode/

.vscode/launch.json

@@ -0,0 +1,16 @@
+{
+    // Use IntelliSense to learn about possible attributes.
+    // Hover to view descriptions of existing attributes.
+    // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+    "version": "0.2.0",
+    "configurations": [
+        {
+            "name": "Python: Current File",
+            "type": "python",
+            "request": "launch",
+            "program": "${file}",
+            "console": "integratedTerminal",
+            "justMyCode": false
+        }
+    ]
+}

.vscode/ltex.dictionary.en-US.txt

@@ -0,0 +1 @@
+AutoPR

.vscode/settings.json

@@ -0,0 +1,25 @@
+{
+    "python.testing.pytestArgs": [
+        "autopr"
+    ],
+    "python.testing.unittestEnabled": false,
+    "python.testing.pytestEnabled": true,
+    "cSpell.words": [
+        "autopr",
+        "Pydantic",
+        "subfolders",
+        "todos"
+    ],
+    "yaml.schemas": {
+        "./trigger_schema.json": [
+          ".autopr/triggers.{yaml,yml}",
+          ".autopr/triggers/*.{yaml,yml}",
+          "autopr/tests/triggers/*.{yaml,yml}"
+        ],
+        "./workflow_schema.json": [
+            ".autopr/workflows.{yaml,yml}",
+            ".autopr/workflows/*.{yaml,yml}",
+            "autopr/tests/workflow_resources/*.{yaml,yml}"
+        ]
+    }    
+}

autopr/actions/comment.py

@@ -11,6 +11,9 @@ class Inputs(BaseModel):
 
 
 class Comment(Action[Inputs, None]):
+    """
+    A class representing an action to publish a comment on a GitHub issue.
+    """
     id = "comment"
 
     async def run(self, inputs: Inputs) -> None:

autopr/actions/commit_and_push.py

@@ -11,6 +11,10 @@ class Inputs(pydantic.BaseModel):
 
 
 class CommitAndPush(Action[Inputs, None]):
+    """
+    A class that represents an action to commit and push changes to a remote repository.
+    """
+
     id = "commit_and_push"
 
     async def run(self, inputs: Inputs) -> None:

autopr/actions/crawl_folder.py

@@ -59,8 +59,10 @@ class Outputs(BaseModel):
 
 
 class CrawlFolder(Action[Inputs, Outputs]):
+    """
+    This action lists all the files and subfolders in a folder, excluding certain files and directories.
+    """
     id = "crawl_folder"
-    description = "List all the files and subfolders in a folder"
 
     @staticmethod
     def is_binary(path):

autopr/actions/edit_file.py

@@ -68,8 +68,10 @@ class Outputs(BaseModel):
 
 
 class EditFile(Action[Inputs, Outputs]):
+    """
+    An action that rewrites a code hunk in a file.
+    """
     id = "edit_file"
-    description = "Rewrite a code hunk in a file."
 
     @staticmethod
     def _split_into_lines(text: str) -> list[str]:

autopr/actions/insert_content_into_text.py

@@ -24,8 +24,12 @@ class Outputs(BaseModel):
 
 
 class InsertContentIntoText(Action[Inputs, Outputs]):
+    """
+    This action inserts content into a string at a specified delimiter. If the delimiter occurs only once in the string,
+    the content is appended to the end of the string with delimiters. If the delimiter occurs two or more times, the
+    content is inserted between the last two delimiters.
+    """
     id = "insert_content_into_text"
-    description = "Insert content into text."
 
     @staticmethod
     def insert_tag_content_into_string(

autopr/actions/new_file.py

@@ -49,8 +49,11 @@ class Outputs(BaseModel):
 
 
 class NewFile(Action[Inputs, Outputs]):
+    """
+    An action that creates a new file in the repository.
+    """
+
     id = "new_file"
-    description = "Make a new file."
 
     async def run(self, inputs: Inputs) -> Outputs:
         await self.publish_service.update_section(title=f"📄 Creating new file: {inputs.filepath}")

autopr/actions/plan_pr.py

@@ -39,8 +39,10 @@ class Outputs(BaseModel):
 
 
 class PlanPullRequest(Action[Inputs, Outputs]):
+    """
+    Propose a pull request to the user.
+    """
     id = "plan_pull_request"
-    description = "Propose a pull request to the user."
 
     def propose_pull_request(self, issue: Issue, notes: str) -> PullRequestDescription:
         self.log.debug('Getting commit messages...')

autopr/actions/prompt.py

@@ -46,8 +46,10 @@ class Outputs(BaseModel):
 
 
 class PromptString(Action[Inputs, Outputs]):
+    """
+    Prompt to generate a string.
+    """
     id = "prompt"
-    description = "Prompt to generate a string."
 
     def filter_nones(self, d):
         if isinstance(d, dict):

autopr/actions/read_file.py

@@ -21,8 +21,10 @@ class Outputs(BaseModel):
 
 
 class ReadFile(Action[Inputs, Outputs]):
+    """
+    A class representing an action to read the contents of a file.
+    """
     id = "read_file"
-    description = "Read the contents of a file"
 
     @staticmethod
     def load_jupyter_notebook(inputs: Inputs) -> str:

autopr/actions/request_more_info.py

@@ -10,8 +10,10 @@ class Inputs(BaseModel):
 
 
 class RequestMoreInfo(Action[Inputs, None]):
+    """
+    A class representing an action to request more information from the user.
+    """
     id = "request_more_information"
-    description = "Request more information from the user."
 
     async def run(self, inputs: Inputs) -> None:
         # Add a comment to the issue

autopr/actions/set_issue_title.py

@@ -8,6 +8,9 @@ class Inputs(BaseModel):
 
 
 class SetIssueTitle(Action[Inputs, None]):
+    """
+    A class representing an action to set the title of an issue.
+    """
     id = "set_issue_title"
 
     async def run(self, inputs: Inputs) -> None:

autopr/actions/write_into_file.py

@@ -24,8 +24,10 @@ class Outputs(BaseModel):
 
 
 class WriteIntoFile(Action[Inputs, Outputs]):
+    """
+    This action writes content into a file.
+    """
     id = "write_into_file"
-    description = "Write into a file."
 
     async def run(self, inputs: Inputs) -> Outputs:
         with open(inputs.filepath, "a" if inputs.append_at_the_end else "w") as f:

docs/docs/action-catalogue.mdx

@@ -0,0 +1,101 @@
+---
+sidebar_position: 8
+---
+
+# 💧 Action Catalogue
+
+See here for a list of available actions to use in your workflows.
+
+## `bash`
+
+Run a bash command and return its output.
+
+Inputs:
+- `command`: The command to run.
+
+Outputs:
+- `stdout`: The standard output of the command.
+- `stderr`: The standard error of the command.
+
+## `comment`
+
+Posts a comment on an issue or pull request.
+
+Inputs:
+- `comment`: The body of the comment.
+- `issue_number`: The number of the issue or pull request to comment on. Optional, defaults to the pull request.
+
+## `commit_and_push`
+
+Commits and pushes the changes to the current branch.
+
+Inputs:
+- `commit_message`: The commit message. Optional, defaults to "AutoPR commit".
+- `filepaths`: The filepaths to commit. Optional, defaults to all files.
+
+## `crawl_folder`
+
+This action lists all the files and subfolders in a folder, excluding certain files and directories.
+
+Inputs:
+- `folder_path`: The folder to crawl.
+- `entries_to_ignore`: Files and subfolders to ignore during the crawl. Optional, defaults to `[]`.
+- `ignore_binary_files`: Whether to ignore binary files. Optional, defaults to `True`.
+
+Outputs:
+- `contents`: The list of files in the folder.
+
+## `insert_content_into_text`
+
+This action inserts content into a string at a specified delimiter. If the delimiter occurs only once in the string,
+the content is appended to the end of the string with delimiters. If the delimiter occurs two or more times, the
+content is inserted between the last two delimiters.
+
+Inputs:
+- `existing_content`: The existing content of the file/text etc.
+- `delimiter`: The delimiter to insert the content after. Example: `<!-- tag -->`
+- `content_to_add`: The content to insert
+
+Outputs:
+- `content`: The content of the file after the insertion
+
+
+## `prompt`
+
+Prompt the language model to generate a string.
+
+Inputs:
+- `model`: The model to use to generate the variable. Optional, defaults to "gpt-3.5-turbo-16k".
+- `prompt_context`: The context headings that are used to generate the variable. Optional, defaults to `None`.
+- `instructions`: The instructions to use to generate the variable. Optional, defaults to `""`.
+- `prompt`: The prompt to use to generate the variable. Optional, defaults to `""`.
+- `max_prompt_tokens`: Max tokens to use for the prompt. Optional, defaults to `8000`.
+- `max_response_tokens`: Max tokens to use for the response. Optional, defaults to `2000`.
+- `temperature`: The temperature to use for the response. Optional, defaults to `0.6`.
+
+Outputs:
+- `result`: The result of the LLM call.
+
+## `read_file.py`
+
+A class representing an action to read the contents of a file.
+
+Inputs:
+- `file_path`: The path to the file to read.
+- `ensure_exists`: Whether to raise an error if the file does not exist. Optional, defaults to `True`.
+
+Outputs:
+- `content`: The contents of the file.
+- `success`: Whether the file was read successfully.
+
+## `write_into_file.py`
+
+This action writes content into a file.
+
+Inputs:
+- `filepath`: The path of the file you want to write into.
+- `content`: The content to insert.
+- `append_at_the_end`: Whether to append the content just to the end of the file, or replace the entire file content. Optional, defaults to `True`.
+
+Outputs:
+- `success`: If the file was written to successfully.

docs/docs/configuring.md

@@ -4,9 +4,35 @@ sidebar_position: 3
 
 # ✂️ Configuring
 
-TODO
-- describe structure of .autopr folder
-  - ".autopr/actions" folder is python package for custom Action subclasses
-  - ".autopr/workflows" folder for YAML workflows (and triggers)
-  - maybe ".autopr/config.yml" for general config and configuring existing/default workflows
-- possibly split this into a section with multiple pages, one for each main feature, and on the main page the structure 
+## 📁 The `.autopr` Folder
+
+When you initialize AutoPR for your repository, create a folder named `.autopr`.
+Think of this directory as AutoPR's command center, where it looks for instructions on what to do.  
+Inside this folder, there are a few important files and folders:
+
+- `.autopr/triggers.yaml`: Tells AutoPR when to act.
+- `.autopr/workflows.yaml`: Optionally defines custom workflows for AutoPR to execute.
+- `.autopr/cache`: Where AutoPR stores its cache files.
+  At the moment, action `prompt` (for executing LLM prompts) implements caching in the background.
+
+## 🏁 Setting Triggers in `.autopr/triggers.yaml`
+
+Triggers serve as conditions or events that, when met, initiate specific actions,
+such as pushing to a branch, or labeling a pull request.
+
+See [the triggers reference](../reference/triggers) for a full list of triggers and their descriptions.
+
+## 🛠️ Writing Workflows in `.autopr/workflows.yaml`
+
+There are a few predefined workflows that you can use out of the box.  
+See [the workflow catalogue](../workflow-catalogue) for a full list of workflows and their descriptions.
+
+AutoPR is designed to be highly flexible and customizable, so you can write your own workflows to automate your repository.  
+See the [tutorial on how to write your own workflows](./tutorials/writing-a-workflow) for more information.
+
+## 🚀 Ready, Set, Go!
+
+And that's it! With your triggers set and workflows defined, AutoPR is ready to work its magic on your repository. 
+Remember, you can always come back and tweak these configurations as your needs evolve. AutoPR is designed to be flexible and grow with you. 🌟
+
+If you have any questions, or you need assistance with writing custom trigger files or workflows, feel free to reach out to us on [Discord](https://discord.com/invite/ykk7Znt3K6) or [post an issue on Github](https://github.com/irgolic/AutoPR/issues).