Updated developer docs: 2024-10-11T21:36:41+0000

Author: rolandstdocs

docs/Internal-Docs/Customize-Your-AI-Generation.md

@@ -29,7 +29,7 @@ Find your `dev-docs.json` file.
 
 ## Step 4: Customize the JSON
 
-Now we are going to make your Dev-Docs JSON look similar to the one in the step above.  The goal is have the AI answer custom questions and prompts on our code.  Replace your JSON with JSON below:
+Now we are going to make your Dev-Docs JSON look similar to the one in the step above. The goal is have the AI answer custom questions and prompts on our code. Replace your JSON with JSON below:
 
 ```json
 
@@ -44,7 +44,7 @@ Now we are going to make your Dev-Docs JSON look similar to the one in the step
                     "documentation": ""
                 },
                 {
-                    "question": "Is this code written well?  if so Why?",
+                    "question": "Is this code written well? If so why?",
                     "title": "Quality of Code",
                     "documentation": ""
                 }

docs/Internal-Docs/Generate-Documentation-With-AI.md

@@ -14,6 +14,7 @@ sidebar_position: 4
 
 # Generate Documentation with AI
 
+Out of the box, Dev-Docs will document your codebase by letting you know what each function, class, or variable does on a case by base basis. Below you'll see a step by step guide on how to start generating docs from your VS Code editor.
 
 ## Step 1: Sign into Dev-Docs in VS Code
 
@@ -39,7 +40,7 @@ Select the file you wish to be documented. From there, open the command palette,
 
 ## Step 4: Review the AI Generated Documentation
 
-Wait a couple minutes and find the corresponding Dev-Docs markdown file to check if documentation was generated.
+In just a few minutes you'll see a new Markdown file generated in the Dev-Docs folder in your repo. You can view the raw Markdown there or right click on the file you generated docs for and navigate to **Open Devdocs Markdown** to view it in a rich text editor right next to the file itself. 
 
 ![](/img/generate_documentation_with_ai/step_7.png)
 

docs/Internal-Docs/Intro-to-Dev-Docs-Internal-Documentation.md

@@ -4,4 +4,6 @@ sidebar_position: 1
 
 # Intro to Dev-Docs Internal Documentation
 
-Internal Documentation refers to documentation intended for developers contributing to your codebase. This can be applied to any project, whether it be for an open source project, a team, a department, or a whole company. This section will break down how to get started with Dev-Docs Internal Documentation. 
+Internal Documentation refers to documentation intended for your own teams. This can be applied to any project, whether it be for an open source project, a team, a department, or a whole company. Dev-Docs will generate Markdown files for you with no configuration needed. However, you do have the ability to configure exactly what you want with the `dev-docs.json`. This includes what code you want documented, what questions you want answered of your code, and if you want it pushed to any external source (Confluence, Notion, or Google Drive). 
+<br></br>
+Whether you need documentation to help onboard new hires, for devs contributing to your codebase or to keep the broader organization up to date, Dev-Docs has your back. This section will break down how to start generating docs for your team and how to configure exactly what you want documented.

docs/Internal-Docs/Install-the-Extension-and-Create-Your-First-Internal-Docs.md renamed to docs/Internal-Docs/_Install-the-Extension-and-Create-Your-First-Internal-Docs.md

@@ -4,18 +4,19 @@ slug: /VS-Code-Commands/Audit-Docs
 
 # Audit Docs
 
-**What does this VS Code Extension Command do?**
+## What Does This VS Code Extension Command Do?
+
 The `devdocs.auditDocs` command is used to audit the existing documentation files in the project. It analyzes the Markdown files and identifies potential issues or areas for improvement, such as grammar or spelling errors, unclear or unhelpful content, and opportunities to enhance the aesthetic appeal of the documentation.
 
-**Why should I use this VS Code Extension Command?**
+## Why Should I Use This VS Code Extension Command?
+
 Maintaining high-quality documentation is crucial for effective communication and collaboration within a project. By using the `devdocs.auditDocs` command, you can ensure that your documentation remains accurate, clear, and visually appealing. This command helps you identify and address any issues or inconsistencies in your documentation, improving its overall quality and usefulness.
 
-**What are relevant configuration Options in the `dev-docs.json`?**
-The following configuration options in the `dev-docs.json` file are relevant to the `devdocs.auditDocs` command:
+## What are relevant configuration Options in the `dev-docs.json`?
 
 - `ai.auditTasks`: This option allows you to specify additional custom tasks or criteria for auditing the documentation. It is an array of strings, where each string represents a specific task or aspect to be evaluated during the audit process.
 
-**Example JSON of relevant Dev-Docs.json options**
+## Example JSON of relevant Dev-Docs.json options
 ```json
 {
   "ai": {
@@ -27,23 +28,28 @@ The following configuration options in the `dev-docs.json` file are relevant to
 }
 ```
 
-**Prerequisites**
+## Prerequisites
+
 Before using the `devdocs.auditDocs` command, make sure you have the following:
 
 1. A `dev-docs.json` configuration file in your project's root directory.
-2. Markdown files containing the documentation you want to audit.
-3.  You using it in a dev-docs documentation repo.
+2. The repo contains Markdown files of the documentation you want to audit.
+
+## How Do I Use This VS Code Extension Command?
 
-**How do I use this VS Code Extension Command?**
 To use the `devdocs.auditDocs` command, follow these steps:
 
-1. Open your project in Visual Studio Code.
+<br></br>
+
+1. Open your project in VS Code
 2. Open the Command Palette by pressing `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (Mac).
 3. Type "Dev-Docs: Audit Your Docs" or "devdocs.auditDocs" and select the command from the list.
 4. The extension will analyze your Markdown files and identify potential issues based on the configured audit tasks.
 5. A new Markdown file named `dev-docs_audit.md` will be generated in the `docs` directory, containing the audit results and suggestions for improvements.
 6. If any issues are found, the extension will also create GitHub issues for each file with identified problems, providing links to the issues within the `dev-docs_audit.md` file.
 
+<br></br>
+
 By regularly auditing your documentation using the `devdocs.auditDocs` command, you can ensure that your project's documentation remains accurate, clear, and visually appealing, facilitating better understanding and collaboration among team members and users.
 
 

docs/VS Code Commands/Auditing-Documentation-Using-the-devdocs.auditdocs-Command.md

@@ -6,14 +6,16 @@ slug: /VS-Code-Commands/Clear-Dev-Docs-Tokens
 
 This command clears the Dev-Docs authentication tokens stored locally on your machine. It removes the GitHub access token and refresh token used to authenticate with the Dev-Docs Cloud service.
 
-## What does this VS Code Extension Command do?
+## What Does This VS Code Extension Command Do?
 
 The `devdocs.resetTokens` command removes the locally stored Dev-Docs authentication tokens from your machine. It essentially logs you out of the Dev-Docs Cloud service, revoking access to your account and any associated documentation repositories.
 
-## Why should I use this VS Code Extension Command?
+## Why Should I Use This VS Code Extension Command?
 
 You might want to use this command in the following scenarios:
 
+<br></br>
+
 1. **Sign Out**: If you want to sign out of your Dev-Docs Cloud account on the current machine, running this command will revoke access and clear your stored credentials.
 
 2. **Token Expiration/Revocation**: If your Dev-Docs authentication tokens have expired or been revoked for security reasons, running this command will ensure the old tokens are removed before generating new ones.
@@ -22,26 +24,22 @@ You might want to use this command in the following scenarios:
 
 4. **Troubleshooting**: In case of authentication issues or other token-related problems, clearing the existing tokens can help resolve the issue by starting with a clean slate.
 
-## What are relevant configuration Options in the `dev-docs.json`?
-
-The `dev-docs.json` configuration file does not have any options directly related to the `devdocs.resetTokens` command. This command operates on the locally stored authentication tokens and does not require any specific configuration options.
-
-## Example JSON of relevant Dev-Docs.json options
-
-Since this command does not require any configuration options in the `dev-docs.json` file, there is no example JSON to provide.
-
 ## Prerequisites
 
 To use the `devdocs.resetTokens` command, you must have previously authenticated with the Dev-Docs Cloud service using the `devdocs.getGitHubUser` command or an equivalent authentication flow.
 
-## How do I use this VS Code Extension Command?
+## How Do I Use This VS Code Extension Command?
 
 To clear your Dev-Docs authentication tokens, follow these steps:
 
-1. Open the Visual Studio Code Command Palette by pressing `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS).
+<br></br>
+
+1. Open the VS Code Command Palette by pressing `Ctrl+Shift+P` (Windows/Linux) or `Cmd+Shift+P` (macOS).
 2. Type "Dev-Docs" and select the "Clear dev-docs tokens" command from the list.
 3. Alternatively, you can navigate to the Dev-Docs view in the Activity Bar and click the "Sign Out" link when logged in.
 
-After running the command, your Dev-Docs authentication tokens will be removed from your local machine. You will need to re-authenticate with the `devdocs.getGitHubUser` command to regain access to the Dev-Docs Cloud service.
+<br></br>
+
+After running the command, your Dev-Docs authentication tokens will be removed from your local machine. You will need to sign in and re-authenticate with the `devdocs.getGitHubUser` command to regain access to the Dev-Docs Cloud service.
 
 

docs/VS Code Commands/Clear-Dev-Docs-Authentication-Tokens.md

@@ -6,10 +6,12 @@ slug: /VS-Code-Commands/Generating-API-Documentation-and-Config
 
 The `devdocs.generateAPIDocumentation` command allows you to generate API documentation and configuration files directly from your codebase. It analyzes your code, identifies API routes, and generates a Postman Collection JSON file containing all the detected API routes. Additionally, it can generate an OpenAPI (Swagger) specification file for your API.
 
-## Why should I use this VS Code Extension Command?
+## Why Should I Use This VS Code Extension Command?
 
 Generating API documentation from your codebase has several advantages:
 
+<br></br>
+
 1. **Keeps Documentation Synchronized with Code**: By generating documentation directly from your code, you ensure that your API documentation stays up-to-date with the latest changes in your codebase, reducing the risk of documentation drift.
 
 2. **Saves Time and Effort**: Manually documenting APIs can be a time-consuming and error-prone process. This command automates the process, saving you valuable time and effort.
@@ -22,6 +24,8 @@ Generating API documentation from your codebase has several advantages:
 
 The following configuration options in the `dev-docs.json` file are relevant for the `devdocs.generateAPIDocumentation` command:
 
+<br></br>
+
 - `ai.openapi.file`: Specifies the file path where the generated OpenAPI specification file should be saved.
 
 ## Example JSON of relevant Dev-Docs.json options
@@ -38,18 +42,22 @@ The following configuration options in the `dev-docs.json` file are relevant for
 
 ## Prerequisites
 
-- Your project should have a `dev-docs.json` configuration file in the root directory.
-- The `dev-docs.json` file should be properly configured with the relevant options mentioned above.
+1. Your project should have a `dev-docs.json` configuration file in the root directory.
+2. The `dev-docs.json` file should be properly configured with the relevant options mentioned above.
 
-## How do I use this VS Code Extension Command?
+## How Do I Use This VS Code Extension Command?
 
 1. **Open the command palette**: Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) to open the command palette.
 2. **Search for the command**: Type `devdocs.generateAPIDocumentation` and select it from the list.
 3. **Wait for the generation process**: The extension will analyze your codebase, identify API routes, and generate the Postman Collection JSON file and OpenAPI specification file based on your configuration.
 4. **Review the generated files**: Once the process is complete, you can find the generated files in the locations specified in your `dev-docs.json` configuration.
 
+<br></br>
+
 The generated Postman Collection JSON file can be imported into Postman or other compatible tools for testing and documentation purposes. The OpenAPI specification file can be used for generating client libraries, documentation, or integrating with other tools that support the OpenAPI standard.
 
+<br></br>
+
 By following this process, you can ensure that your API documentation stays up-to-date with your codebase, improving developer experience and facilitating collaboration within your team or with external partners.
 
 

docs/VS Code Commands/Generate-API-Documentation-from-Codebase.md

@@ -6,17 +6,17 @@ slug: /VS-Code-Commands/Generate-Context-for-Multiple-Documents
 
 The `devdocs.generateMultiContext` command is used to generate high-level context for multiple code files or directories within the current workspace. This command is particularly useful when you have a project with multiple files or folders, and you want to generate a brief overview or summary for each of them.
 
-## Why should I use this VS Code Extension Command?
+## Why Should I Use This VS Code Extension Command?
 
 Creating high-level context for multiple files or directories can be a time-consuming and repetitive task, especially in large projects. By using this command, you can automate the process of generating context, saving you time and effort. Additionally, having a concise overview of each file or directory can help you better understand the structure and purpose of your project, making it easier to navigate and maintain.
 
 ## What are relevant configuration Options in the `dev-docs.json`?
 
 The following configuration options in the `dev-docs.json` file are relevant for this command:
 
-- `ai.contextDirs`: An array of directories to generate high-level context for. By default, it includes `["src/utils", "src/helpers"]`.
-- `customRoot`: The custom root directory for your project, relative to the workspace root. This option helps the extension find the correct files and directories.
-- `workspaceRoot`: The absolute path to the root directory of your workspace.
+1. `ai.contextDirs`: An array of directories to generate high-level context for. By default, it includes `["src/utils", "src/helpers"]`.
+2. `customRoot`: The custom root directory for your project, relative to the workspace root. This option helps the extension find the correct files and directories.
+3. `workspaceRoot`: The absolute path to the root directory of your workspace.
 
 ## Example JSON of relevant Dev-Docs.json options
 
@@ -34,21 +34,29 @@ The following configuration options in the `dev-docs.json` file are relevant for
 
 Before using this command, make sure you have:
 
+<br></br>
+
 1. A `dev-docs.json` file configured with the relevant options mentioned above.
 2. Code files or directories for which you want to generate context.
 
-## How do I use this VS Code Extension Command?
+## How Do I Use This VS Code Extension Command?
 
 To use the `devdocs.generateMultiContext` command, follow these steps:
 
+<br></br>
+
 1. Open the Command Palette in Visual Studio Code (`Ctrl+Shift+P` or `Cmd+Shift+P`).
 2. Search for `Generate Context for Multiple Documents` and select the command.
 3. The extension will scan your workspace for the specified code files and directories based on the `dev-docs.json` configuration.
 4. For each file or directory, the extension will attempt to generate a high-level context summary.
 5. The generated context will be displayed in the output panel or a new editor tab, depending on the extension's settings.
 
+<br></br>
+
 The generated context aims to provide a brief overview of the purpose, functionality, and any relevant information about the code file or directory. This can help you quickly understand the role of each component within your project, facilitating better code comprehension and maintenance.
 
+<br></br>
+
 It's important to note that the quality and accuracy of the generated context may vary depending on the complexity of your code and the capabilities of the AI model used by the extension. Additionally, the extension's behavior and output format may be subject to change or improvements in future updates.
 
 

docs/VS Code Commands/Generate-Context-for-Multiple-Documents.md

@@ -6,14 +6,16 @@ slug: /VS-Code-Commands/Generate-High-Level-Context-for-the-Folder
 
 This VS Code extension command allows you to generate a high-level overview or context for the entire folder or directory. It analyzes all the code files within the folder and provides a comprehensive summary of what the folder's purpose is and what it does from a high-level perspective.
 
-## Why should I use this VS Code Extension Command?
+## Why Should I Use This VS Code Extension Command?
 
 Generating a high-level context for a folder can be extremely useful when working on large codebases or projects with multiple files and directories. It helps you understand the overall purpose and functionality of a specific folder without having to dive into each individual file. This can be particularly beneficial when onboarding new team members, reviewing code, or documenting a project's architecture.
 
 ## What are relevant configuration Options in the `dev-docs.json`?
 
 The relevant configuration options for generating a high-level context for a folder in the `dev-docs.json` file are:
 
+<br></br>
+
 1. **`ai.contextDirs`**: An array of directory paths that should be considered for context generation. By default, it includes `["src/utils", "src/helpers"]`.
 2. **`ai.internalTypeFilters`**: An array of types or elements that should be included in the context generation process. By default, it includes a wide range of types such as classes, methods, functions, and more.
 3. **`customRoot`**: A string that specifies the custom root directory for your project. This can be useful if your project is located within a monorepo or a specific subdirectory.
@@ -51,19 +53,27 @@ The relevant configuration options for generating a high-level context for a fol
 
 Before using the `devdocs.generateFolderContext` command, make sure you have the following prerequisites:
 
+<br></br>
+
 1. A valid `dev-docs.json` configuration file in your project's root directory.
 2. The folder or directory for which you want to generate the high-level context must be within the specified `workspaceRoot` or `customRoot` paths.
 
-## How do I use this VS Code Extension Command?
+## How Do I Use This VS Code Extension Command?
 
 To generate a high-level context for a folder, follow these steps:
 
+<br></br>
+
 1. Open your project in Visual Studio Code.
 2. In the Explorer view, right-click on the folder or directory for which you want to generate the context.
 3. From the context menu, select the "Generate High Level Context for the Folder" option.
 
+<br></br>
+
 Alternatively, you can also trigger the command from the Command Palette (Ctrl+Shift+P or Cmd+Shift+P) by typing "Generate High Level Context for the Folder" and selecting the command.
 
+<br></br>
+
 After running the command, the extension will analyze all the code files within the selected folder and generate a high-level context document. This document will provide an overview of the folder's purpose and functionality, helping you understand the code structure and organization better.