Generate User-Facing Documentation

The "Populate External Docs" command (devdocs.generateExternalDocs) is a crucial feature of the Dev-Docs VS Code extension that allows you to generate comprehensive documentation for your users. This command analyzes your project's files and generates an external documentation website, which serves as a centralized hub for all your project's documentation.

What Does This VS Code Extension Command Do?

The "Populate External Docs" command performs the following tasks:

1. Scans your project's codebase and identifies relevant code elements (classes, functions, methods, etc.) based on the specified filters (internalTypeFilters, codeFilters, nameFilters).
2. Optionally includes code snippets from other files or folders specified in the configuration (importFiles, importFolders).
3. Generates documentation for each identified code element, either by using predefined prompts or employing AI-assisted documentation generation.
4. Organizes the generated documentation into a structured format, following the specified mappings (mappings) and folder structure (docSubFolder).
5. Updates the dev-docs.json file with the generated mappings.
6. Optionally, pushes the updated documentation to a specified Git branch (branch).

Why Should I Use This VS Code Extension Command?

Using the "Populate External Docs" command offers several benefits:

1. Centralized Documentation Hub: It creates a dedicated website for your project's documentation, making it easily accessible and shareable with team members or external stakeholders.
2. Automated Documentation Generation: The command automates the documentation process, saving you time and effort by generating documentation directly from your codebase.
3. Consistency and Maintainability: By tying the documentation to your codebase, you ensure that your documentation remains up-to-date as your code evolves.
4. Customizable Configuration: The dev-docs.json configuration file allows you to tailor the documentation generation process to your project's specific needs, including filtering code elements, specifying import paths, and organizing the documentation structure.

What Are Relevant Configuration Options in the dev-docs.json?

The following configuration options in the dev-docs.json file are relevant for the "Populate External Docs" command:

1. ai.internalTypeFilters: An array of strings specifying the types of code elements to include in the documentation (e.g., ["class", "method", "function"]).
2. ai.codeFilters: An array of strings used to filter code elements based on specific patterns (e.g., ["async function", "export default"]).
3. ai.nameFilters: An array of strings used to filter code elements based on their names (e.g., ["handleSubmit", "render"]).
4. ai.importFiles: An array of file paths specifying additional files to include in the documentation.
5. ai.importFolders: An array of folder paths specifying additional folders to include in the documentation.
6. ai.importTypeFilters: An array of strings specifying the types of code elements to include from the imported files and folders.
7. ai.importCodeFilters: An array of strings used to filter code elements from the imported files and folders based on specific patterns.
8. ai.importNameFilters: An array of strings used to filter code elements from the imported files and folders based on their names.
9. ai.branch: The Git branch to which the updated documentation will be pushed (default: "main").
10. ai.mappings: An array of objects specifying how the generated documentation should be organized and mapped to specific folders or files in the external documentation website.

Example JSON of relevant dev-docs.json options

Here's an example JSON configuration with the minimum required options to use the "Populate External Docs" command:

{
  "ai": {
    "internalTypeFilters": ["class", "method", "function"],
    "codeFilters": ["async function", "export default"],
    "nameFilters": ["handleSubmit", "render"],
    "branch": "main",
    "mappings": [
      {
        "files": ["src/main.ts"],
        "cloudDir": "Getting Started"
      },
      {
        "folder": ["src/components"],
        "cloudDir": "Components"
      }
    ]
  }
}

Prerequisites

Before using the "Populate External Docs" command, ensure that you have the following prerequisites in place:

1. A dev-docs.json configuration file present in your project's root directory, with the necessary configuration options set.
2. A valid authentication token (devdocs_id_token) stored in the VS Code extension's storage, which can be obtained by running the devdocs.getGitHubUser command and authenticating with your GitHub account.

How Do I Use This VS Code Extension Command?

To use the "Populate External Docs" command, follow these steps:

1. Open your project in VS Code.
2. Ensure that the dev-docs.json configuration file is properly set up with the relevant options.
3. Open the Command Palette in VS Code (Ctrl+Shift+P or Cmd+Shift+P).
4. Search for the "Populate External Docs" command (devdocs.generateExternalDocs) and select it.
5. The extension will start analyzing your codebase and generating the external documentation based on the configured settings.
6. Once the process is complete, you should see a success message in the VS Code output panel, indicating that the external documentation has been generated and updated.