diff --git a/drupal-doc-gen/docs1/explanation/understanding_drupal_org_contribution_tracking_with_ct_drupal_explanation_1034c8.md b/drupal-doc-gen/docs1/explanation/understanding_drupal_org_contribution_tracking_with_ct_drupal_explanation_1034c8.md new file mode 100644 index 00000000..1d7fcd8a --- /dev/null +++ b/drupal-doc-gen/docs1/explanation/understanding_drupal_org_contribution_tracking_with_ct_drupal_explanation_1034c8.md @@ -0,0 +1,102 @@ +# Understanding Drupal.org Contribution Tracking with ct_drupal + +**Overview** + +The `ct_drupal` module for Drupal is designed to track user contributions on Drupal.org. It leverages the Drupal.org API to fetch contribution data and store it within the Drupal site, linking contributions to specific user accounts. This explanation delves into the module's core components and how it facilitates contribution tracking. + +**Key Features** + +* **Contribution Tracking:** The primary function is to monitor and record contributions made by users on Drupal.org. +* **User Integration:** It associates Drupal.org usernames with local Drupal user accounts, enabling accurate contribution tracking for each user. +* **API Integration:** It utilizes the Drupal.org API (wrapped by a Guzzle 6 dependency) to retrieve contribution data. + +**Module Components and Their Roles** + +1. **`DrupalContribution.php` (ContributionSource Plugin):** + + * Located at `web/modules/custom/ct_drupal/src/Plugin/ContributionSource/DrupalContribution.php`. + * Implements the `ContributionSourceInterface` from the `ct_manager` module. + * Acts as the core plugin responsible for interacting with the Drupal.org API. + * It is through this plugin the `ct_manager` module knows how to fetch contribution data from Drupal.org. + +2. **`DrupalRetriever.php`:** + + * Located at `web/modules/custom/ct_drupal/src/DrupalRetriever.php`. + * Transforms the raw data received from the Drupal.org API into a format that can be understood and processed by the rest of the contribution tracking system. + * Responsible for data mapping and object creation tailored to local contribution definitions. + +**How Contribution Tracking Works** + +1. **User Configuration:** Administrators must populate the "Drupal.org Username" field on user profiles within the Drupal site. This establishes the link between the Drupal user and their Drupal.org account. +2. **Cron Processing:** During cron runs, the system identifies users with a Drupal.org username configured. +3. **Data Retrieval:** For each identified user, the `DrupalContribution` plugin is invoked. This plugin interacts with the Drupal.org API. +4. **Data Transformation:** The raw API data is then handled by `DrupalRetriever.php` which tranforms the API results into an object that is understood by the system. +5. **Contribution Storage:** The fetched and transformed contribution data is stored and managed by the `ct_manager` module, allowing for reporting and analysis. + +**Dependencies** + +The module has external dependencies managed through Composer. Specifically, it relies on a PHP package for interacting with the Drupal.org API. The module provides a `composer.json` to declare this dependency, and sites that enable the module should declare it's path as a respository. + +**Relationship with `ct_manager`** + +The `ct_drupal` module functions as a plugin for the `ct_manager` module. The plugin provides a way for the contribution manager module to retrieve contributions from Drupal.org. This is thanks to the plugin implementing `ContributionSourceInterface`. This implies that `ct_manager` offers generic contribution management capabilities, and ct_drupal provides Drupal.org-specific data retrieval within that framework. + +--- + +**Dependencies and Tools:** + +**NPM Dependencies:** +**Development Dependencies:** +- markdownlint-cli: ^0.44.0 +- prettier: ^3.4.2 +- remark-cli: ^12.0.1 +- remark-preset-lint-markdown-style-guide: ^6.0.1 +**Composer Dependencies:** +- php: >=8.2 +- axelerant/ct_drupal: * +- axelerant/ct_github: * +- composer/installers: ^2.1 +- cweagans/composer-patches: ^1.7.0 +- drupal/address: ^2.0 +- drupal/admin_toolbar: ^3.0.0 +- drupal/better_exposed_filters: ^7.0 +- drupal/ckeditor: ^1.0 +- drupal/cookies: ^1.2 +- drupal/core: ^10.1 +- drupal/core-composer-scaffold: ^10.1 +- drupal/do_username: ^2.0 +- drupal/field_permissions: ^1.0.0 +- drupal/fixed_block_content: ^1.1 +- drupal/flag: ^4.0 +- drupal/geocoder: ^4.0 +- drupal/geofield: ^1.0 +- drupal/gin: ^4.0.0@alpha +- drupal/google_tag: ^2.0 +- drupal/inline_entity_form: ^3.0 +- drupal/new_relic_rpm: ^2.0 +- drupal/raven: ^6.0 +- drupal/redis: ^1.4.0 +- drupal/select2: ^1.13 +- drupal/slack: ^1.2.0 +- drupal/social_auth: ^4.0 +- drupal/social_auth_google: ^4.0 +- drupal/stable: ^2.0 +- drupal/twig_tweak: ^3.1 +- drush/drush: ^13.0 +- geocoder-php/nominatim-provider: ^5.2 +- npm-asset/jquery-ui-touch-punch: ^0.2.3 +- oomphinc/composer-installers-extender: ^2.0 +- platformsh/config-reader: ^3.0.0 +- vlucas/phpdotenv: ^5.2 +**Composer Development Dependencies:** +- axelerant/db-docker: ^1.1 +- axelerant/drupal-quality-checker: ^1.4 +- behat/mink: ^1.10 +- behat/mink-browserkit-driver: ^2.1 +- phpunit/phpunit: ^9.0 +- symfony/browser-kit: ^7.0 +- weitzman/drupal-test-traits: ^2.0 + +--- + +**Original Source:** ct_drupal \ No newline at end of file diff --git a/drupal-doc-gen/docs1/explanation/understanding_the_contribution_plugin_manager_explanation_e6b0d9.md b/drupal-doc-gen/docs1/explanation/understanding_the_contribution_plugin_manager_explanation_e6b0d9.md new file mode 100644 index 00000000..6adbd54c --- /dev/null +++ b/drupal-doc-gen/docs1/explanation/understanding_the_contribution_plugin_manager_explanation_e6b0d9.md @@ -0,0 +1,97 @@ +# Understanding the Contribution Plugin Manager + +**Introduction** + +The Contribution Plugin Manager module (ct_manager) provides a flexible way to track and manage user contributions from various sources within a Drupal environment. It allows you to create custom plugins, each responsible for fetching contribution data from a specific origin (e.g., GitHub, GitLab, internal systems). It then processes this data, stores relevant information, and optionally sends notifications about recent contributions, for example, via Slack. + +**Core Functionality** + +At its heart, ct_manager automates the process of gathering, storing, and reporting on user contributions by performing the following steps during a cron run: + +1. **Plugin Discovery:** The module identifies all installed plugins of the `ContributionSource` type. These plugins define how to interact with specific contribution sources. +2. **Plugin Instantiation:** It creates an instance of each discovered `ContributionSource` plugin. +3. **User Processing:** It then adds users to a queue, which it processes in order to track and store contributions for each user from all configured sources. +4. **Contribution Tracking:** For each user, the module uses the `ContributionSource` plugins to retrieve contribution data. +5. **Storage:** Contribution data is stored within the Drupal system (the exact storage mechanism is not specified, but could involve entities, custom tables, etc.). +6. **Notification (Optional):** Optionally, ct\_manager can send notifications (e.g., to a Slack channel) about contributions made within a recent time period (e.g., the last hour). + +**Plugin Architecture** + +The extensibility of ct\_manager comes from its plugin-based architecture. New contribution sources can be added without modifying the core module code. + +* **`ContributionSource` Plugin Type:** The module uses Drupal's Plugin API to define a specific plugin type called `ContributionSource`. +* **Plugin Implementation:** To create a new contribution source, a plugin must: + * Reside in the `src/Plugin/ContributionSource` directory of your module. + * Be annotated with `@ContributionSource`. + * Implement the `ContributionSourceInterface`. This interface defines the methods that the core ct\_manager module will use to interact with the plugin. + * Follow patterns demonstrated in the `ct_github` module example for creating plugins. + +**Key Components** + +* **`ct_manager.module`:** This file executes the main logic during cron runs. It discovers plugins, creates instances of them, and enqueues users for processing. +* **`ContributionSourceInterface.php`:** This interface defines the contract that all `ContributionSource` plugins must adhere to. It specifies the methods that the ct\_manager module will call on each plugin. +* **`ProcessUsers.php`:** This file implements a Drupal QueueWorker plugin that processes the queue of users. For each user, it retrieves contribution data using the configured `ContributionSource` plugins. + +**In Summary** + +The Contribution Plugin Manager is designed to streamline the process of gathering, storing, and reporting user contributions across multiple platforms within a Drupal environment. Its plugin-based architecture enables extensibility and customization to support diverse contribution sources. Understanding its core functionality, plugin architecture, and key components will help developers effectively leverage and extend its capabilities. + +--- + +**Dependencies and Tools:** + +**NPM Dependencies:** +**Development Dependencies:** +- markdownlint-cli: ^0.44.0 +- prettier: ^3.4.2 +- remark-cli: ^12.0.1 +- remark-preset-lint-markdown-style-guide: ^6.0.1 +**Composer Dependencies:** +- php: >=8.2 +- axelerant/ct_drupal: * +- axelerant/ct_github: * +- composer/installers: ^2.1 +- cweagans/composer-patches: ^1.7.0 +- drupal/address: ^2.0 +- drupal/admin_toolbar: ^3.0.0 +- drupal/better_exposed_filters: ^7.0 +- drupal/ckeditor: ^1.0 +- drupal/cookies: ^1.2 +- drupal/core: ^10.1 +- drupal/core-composer-scaffold: ^10.1 +- drupal/do_username: ^2.0 +- drupal/field_permissions: ^1.0.0 +- drupal/fixed_block_content: ^1.1 +- drupal/flag: ^4.0 +- drupal/geocoder: ^4.0 +- drupal/geofield: ^1.0 +- drupal/gin: ^4.0.0@alpha +- drupal/google_tag: ^2.0 +- drupal/inline_entity_form: ^3.0 +- drupal/new_relic_rpm: ^2.0 +- drupal/raven: ^6.0 +- drupal/redis: ^1.4.0 +- drupal/select2: ^1.13 +- drupal/slack: ^1.2.0 +- drupal/social_auth: ^4.0 +- drupal/social_auth_google: ^4.0 +- drupal/stable: ^2.0 +- drupal/twig_tweak: ^3.1 +- drush/drush: ^13.0 +- geocoder-php/nominatim-provider: ^5.2 +- npm-asset/jquery-ui-touch-punch: ^0.2.3 +- oomphinc/composer-installers-extender: ^2.0 +- platformsh/config-reader: ^3.0.0 +- vlucas/phpdotenv: ^5.2 +**Composer Development Dependencies:** +- axelerant/db-docker: ^1.1 +- axelerant/drupal-quality-checker: ^1.4 +- behat/mink: ^1.10 +- behat/mink-browserkit-driver: ^2.1 +- phpunit/phpunit: ^9.0 +- symfony/browser-kit: ^7.0 +- weitzman/drupal-test-traits: ^2.0 + +--- + +**Original Source:** ct_manager \ No newline at end of file diff --git a/drupal-doc-gen/docs1/explanation/understanding_the_ct_github_module__tracking_github_contributions_in_drupal_explanation_6c3723.md b/drupal-doc-gen/docs1/explanation/understanding_the_ct_github_module__tracking_github_contributions_in_drupal_explanation_6c3723.md new file mode 100644 index 00000000..cc7f8a54 --- /dev/null +++ b/drupal-doc-gen/docs1/explanation/understanding_the_ct_github_module__tracking_github_contributions_in_drupal_explanation_6c3723.md @@ -0,0 +1,105 @@ +# Understanding the ct_github Module: Tracking GitHub Contributions in Drupal + +**Introduction:** + +The `ct_github` module is a custom Drupal module designed to track contributions (specifically issues and pull requests) made by users on GitHub. It leverages the GitHub GraphQL API to collect this data and integrates it into a Drupal-based contribution tracking system. + +**Key Concepts:** + +* **ContributionSource Plugin:** The core of the module is implemented as a `ContributionSource` plugin. This plugin conforms to the `ContributionSourceInterface` defined by the `ct_manager` module. This design allows the system to be extended with other contribution sources beyond just GitHub. + +* **GitHub GraphQL API:** The module uses GitHub's GraphQL API for efficient data retrieval. This API allows for precise requests, minimizing the amount of data transferred compared to traditional REST APIs. + +* **User Field:** A custom field is added to the Drupal user entity. This field is used to store the associated GitHub username for each user being tracked. + +* **Cron Integration:** The contribution tracking process is triggered by Drupal's cron system. During a cron run, the module gathers GitHub usernames from users with the custom field populated and queries the GitHub API for their contributions. + +**Module Structure:** + +The module comprises several key files, including: + +* `GithubContribution.php`: (located in `web/modules/custom/ct_github/src/Plugin/ContributionSource/`) This file implements the `ContributionSource` plugin. It contains the logic for connecting to the GitHub API, querying for a user's contributions, and formatting the data for storage within Drupal. It relies on the functionality provided by the `GithubQuery` class. + +* `GithubQuery.php`: (located in `web/modules/custom/ct_github/src/GithubQuery.php`) This handles the specifics of constructing and executing GraphQL queries to the GitHub API. It encapsulates the API interaction logic and simplifies the plugin. This class likely handles authentication and error handling related to communicating with the GitHub API. + +**How it Works:** + +1. **User Configuration:** An administrator configures the Drupal site by adding GitHub usernames to the "Github Username" field for relevant user accounts. + +2. **Cron Trigger:** The Drupal cron system executes the `ct_github` module's update process. + +3. **Data Retrieval:** The module iterates through users who have a GitHub username configured. For each user, it uses the `GithubQuery` class to construct and execute a GraphQL query to the GitHub API. + +4. **Data Processing:** The GitHub API returns data about the user's contributions (issues and pull requests). The `GithubContribution` plugin processes this data, potentially filtering, formatting, and transforming it. + +5. **Storage:** The processed contribution data is stored, likely within the `ct_manager` module's data structure, linking the contribution to the corresponding Drupal user. + +**Requirements and Dependencies:** + +* **GitHub Personal Access Token:** A GitHub personal access token is required to authenticate with the GitHub API. This token should be stored securely, ideally using environment variables or Drupal's configuration management features. + +* **Composer Dependency:** The module likely relies on a PHP package for interacting with the GitHub GraphQL API. This package is managed using Composer. The module needs to ensure its dependencies are properly included and updated by adding the module's composer file as a path repository in the project's composer.json. + +* **ct_manager module:** The module is dependent on the `ct_manager` module, which provides the API and data structures for managing contributions. + +**In summary,** the `ct_github` module provides a streamlined approach to tracking GitHub contributions within a Drupal environment. By leveraging the GitHub GraphQL API and integrating with Drupal's user and cron systems, it enables administrators to monitor and manage user contributions effectively. Understanding the role of the `GithubContribution` plugin, the `GithubQuery` class, and the module's dependencies is crucial for maintaining and extending this functionality. + +--- + +**Dependencies and Tools:** + +**NPM Dependencies:** +**Development Dependencies:** +- markdownlint-cli: ^0.44.0 +- prettier: ^3.4.2 +- remark-cli: ^12.0.1 +- remark-preset-lint-markdown-style-guide: ^6.0.1 +**Composer Dependencies:** +- php: >=8.2 +- axelerant/ct_drupal: * +- axelerant/ct_github: * +- composer/installers: ^2.1 +- cweagans/composer-patches: ^1.7.0 +- drupal/address: ^2.0 +- drupal/admin_toolbar: ^3.0.0 +- drupal/better_exposed_filters: ^7.0 +- drupal/ckeditor: ^1.0 +- drupal/cookies: ^1.2 +- drupal/core: ^10.1 +- drupal/core-composer-scaffold: ^10.1 +- drupal/do_username: ^2.0 +- drupal/field_permissions: ^1.0.0 +- drupal/fixed_block_content: ^1.1 +- drupal/flag: ^4.0 +- drupal/geocoder: ^4.0 +- drupal/geofield: ^1.0 +- drupal/gin: ^4.0.0@alpha +- drupal/google_tag: ^2.0 +- drupal/inline_entity_form: ^3.0 +- drupal/new_relic_rpm: ^2.0 +- drupal/raven: ^6.0 +- drupal/redis: ^1.4.0 +- drupal/select2: ^1.13 +- drupal/slack: ^1.2.0 +- drupal/social_auth: ^4.0 +- drupal/social_auth_google: ^4.0 +- drupal/stable: ^2.0 +- drupal/twig_tweak: ^3.1 +- drush/drush: ^13.0 +- geocoder-php/nominatim-provider: ^5.2 +- npm-asset/jquery-ui-touch-punch: ^0.2.3 +- oomphinc/composer-installers-extender: ^2.0 +- platformsh/config-reader: ^3.0.0 +- vlucas/phpdotenv: ^5.2 +**Composer Development Dependencies:** +- axelerant/db-docker: ^1.1 +- axelerant/drupal-quality-checker: ^1.4 +- behat/mink: ^1.10 +- behat/mink-browserkit-driver: ^2.1 +- phpunit/phpunit: ^9.0 +- symfony/browser-kit: ^7.0 +- weitzman/drupal-test-traits: ^2.0 + +--- + +**Original Source:** ct_github \ No newline at end of file diff --git a/drupal-doc-gen/docs1/index.md b/drupal-doc-gen/docs1/index.md new file mode 100644 index 00000000..755d1814 --- /dev/null +++ b/drupal-doc-gen/docs1/index.md @@ -0,0 +1,25 @@ +# Project Documentation Index + +This is the main index page for the project documentation, organized using the Diátaxis framework. + +Okay, here's a Diátaxis-structured documentation outline based on the provided content: + +- **Tutorials:** + - *(None explicitly suggested in the content, this section requires further elaboration with content)* + +- **How-To Guides:** + - **Installing and Enabling Modules:** - Describes how to install and enable the Drupal.org Contribution Tracker, Github Contribution Tracker, and Contribution Plugin Manager modules. (Implied from "Usage" sections) + - **Configuring User Accounts:** - Explains how to add and configure Drupal.org usernames and Github usernames to user entity. (Implied from "Usage" sections and module descriptions). + - **Creating Custom Contribution Sources:** - Provides instruction on how to create a custom Plugin of type "ContributionSource". (Implied from `ct_manager` README). + +- **Reference:** + - **ContributionSource Plugin API:** - Describes the API for creating `ContributionSource` plugins. (Implied from `ct_manager` module description). + - **Drupal.org API:** - Provides reference information about the Drupal.org API used by the `ct_drupal` module. (Implied) + - **GitHub GraphQL API:** - Provides reference information about the GitHub GraphQL API used by the `ct_github` module. (Implied) + +- **Explanation:** + - **Contribution Tracking Concepts:** - Explains the overall architecture and concepts behind the Contribution Tracker system, including the different types of contributions (code, event, non-code). + - **Contribution Processing Workflow:** Explains how the cron handles tracking contributions and processes users. (Implied from `ct_manager` README). + - **Functional Testing with Cypress:** Explains how to run and interpret functional tests for the Contrib Tracker theme (Based on the `/docs/func_testing.md` reference). + +Navigate to the specific sections for more details. \ No newline at end of file diff --git a/drupal-doc-gen/docs1/index_index_6a992d.md b/drupal-doc-gen/docs1/index_index_6a992d.md new file mode 100644 index 00000000..4c9e9734 --- /dev/null +++ b/drupal-doc-gen/docs1/index_index_6a992d.md @@ -0,0 +1,11 @@ +# Project Documentation Index + +This is the main index page for the project documentation, organized using the Diátaxis framework. + +Navigate to the specific sections below for more details: + +- **[Setting up a Local Development Environment for Contribution Tracker (How-To Guide)](setting_up_a_local_development_environment_for_contribution_tracker_how-to guide_7e030b.md)** +- **[Understanding Drupal.org Contribution Tracking with ct_drupal (Explanation)](understanding_drupal_org_contribution_tracking_with_ct_drupal_explanation_1034c8.md)** +- **[Understanding the ct_github Module: Tracking GitHub Contributions in Drupal (Explanation)](understanding_the_ct_github_module__tracking_github_contributions_in_drupal_explanation_6c3723.md)** +- **[Understanding the Contribution Plugin Manager (Explanation)](understanding_the_contribution_plugin_manager_explanation_e6b0d9.md)** +- **[Contrib Tracker Theme (Reference)](contrib_tracker_theme_reference_0258f2.md)** \ No newline at end of file diff --git a/drupal-doc-gen/docs1/reference/contrib_tracker_theme_reference_0258f2.md b/drupal-doc-gen/docs1/reference/contrib_tracker_theme_reference_0258f2.md new file mode 100644 index 00000000..625294f2 --- /dev/null +++ b/drupal-doc-gen/docs1/reference/contrib_tracker_theme_reference_0258f2.md @@ -0,0 +1,69 @@ +# Contrib Tracker Theme + +This section provides a reference to the Contrib Tracker theme. + +**Functional Testing:** + +* For detailed information on functional testing using Cypress with the Contrib Tracker theme, please refer to: + * [IDP Portal](https://idp.axelerant.com/catalog/default/component/contrib-tracker/docs/func_testing/) + * [Source Code](/docs/func_testing.md) + +--- + +**Dependencies and Tools:** + +**NPM Dependencies:** +**Development Dependencies:** +- markdownlint-cli: ^0.44.0 +- prettier: ^3.4.2 +- remark-cli: ^12.0.1 +- remark-preset-lint-markdown-style-guide: ^6.0.1 +**Composer Dependencies:** +- php: >=8.2 +- axelerant/ct_drupal: * +- axelerant/ct_github: * +- composer/installers: ^2.1 +- cweagans/composer-patches: ^1.7.0 +- drupal/address: ^2.0 +- drupal/admin_toolbar: ^3.0.0 +- drupal/better_exposed_filters: ^7.0 +- drupal/ckeditor: ^1.0 +- drupal/cookies: ^1.2 +- drupal/core: ^10.1 +- drupal/core-composer-scaffold: ^10.1 +- drupal/do_username: ^2.0 +- drupal/field_permissions: ^1.0.0 +- drupal/fixed_block_content: ^1.1 +- drupal/flag: ^4.0 +- drupal/geocoder: ^4.0 +- drupal/geofield: ^1.0 +- drupal/gin: ^4.0.0@alpha +- drupal/google_tag: ^2.0 +- drupal/inline_entity_form: ^3.0 +- drupal/new_relic_rpm: ^2.0 +- drupal/raven: ^6.0 +- drupal/redis: ^1.4.0 +- drupal/select2: ^1.13 +- drupal/slack: ^1.2.0 +- drupal/social_auth: ^4.0 +- drupal/social_auth_google: ^4.0 +- drupal/stable: ^2.0 +- drupal/twig_tweak: ^3.1 +- drush/drush: ^13.0 +- geocoder-php/nominatim-provider: ^5.2 +- npm-asset/jquery-ui-touch-punch: ^0.2.3 +- oomphinc/composer-installers-extender: ^2.0 +- platformsh/config-reader: ^3.0.0 +- vlucas/phpdotenv: ^5.2 +**Composer Development Dependencies:** +- axelerant/db-docker: ^1.1 +- axelerant/drupal-quality-checker: ^1.4 +- behat/mink: ^1.10 +- behat/mink-browserkit-driver: ^2.1 +- phpunit/phpunit: ^9.0 +- symfony/browser-kit: ^7.0 +- weitzman/drupal-test-traits: ^2.0 + +--- + +**Original Source:** contribtracker \ No newline at end of file diff --git a/drupal-doc-gen/docs1/setting_up_a_local_development_environment_for_contribution_tracker_how-to guide_7e030b.md b/drupal-doc-gen/docs1/setting_up_a_local_development_environment_for_contribution_tracker_how-to guide_7e030b.md new file mode 100644 index 00000000..53985cc7 --- /dev/null +++ b/drupal-doc-gen/docs1/setting_up_a_local_development_environment_for_contribution_tracker_how-to guide_7e030b.md @@ -0,0 +1,122 @@ +# Setting up a Local Development Environment for Contribution Tracker + +This guide walks you through setting up a local development environment for the Contribution Tracker Drupal application. + +**Prerequisites:** + +Before you begin, ensure you have the following tools installed and configured: + +* **Docker** or **OrbStack**: Used for containerization. +* **DDEV** (v1.23.3 or later): A tool for local PHP development. +* **Git**: For version control and cloning the repository. +* **NodeJs**: for frontend asset management. + +*Note*: It's recommended to have at least 8GB of RAM, ideally 16GB, for a smooth development experience. + +**Steps:** + +1. **Clone the Repository:** + + Use Git to clone the Contribution Tracker repository to your local machine. Open your terminal and run: + + ```bash + git clone git@github.com:contrib-tracker/backend.git + ``` + +2. **Navigate to the Project Directory:** + + Change your current directory to the cloned repository: + + ```bash + cd backend + ``` + +3. **Start DDEV:** + + Start the DDEV environment. This will set up the necessary containers for your Drupal application. + + ```bash + ddev start + ``` + + DDEV will output URLs to access the newly created instance once the setup is complete. + +4. **Install Composer Dependencies:** + + Use DDEV to run Composer and install the project's dependencies. + + ```bash + ddev composer install + ``` + +5. **Pull the Database (Optional):** + + If you have access to the Platform.sh environment, you can pull a copy of the database: + + * Ensure you have the `PLATFORMSH_CLI_TOKEN` environment variable set. Refer to the [DDEV documentation](https://ddev.readthedocs.io/en/latest/users/providers/platform/) for instructions. + + * Run the following command: + + ```bash + ddev pull platform + ``` + +--- + +**Dependencies and Tools:** + +**NPM Dependencies:** +**Development Dependencies:** +- markdownlint-cli: ^0.44.0 +- prettier: ^3.4.2 +- remark-cli: ^12.0.1 +- remark-preset-lint-markdown-style-guide: ^6.0.1 +**Composer Dependencies:** +- php: >=8.2 +- axelerant/ct_drupal: * +- axelerant/ct_github: * +- composer/installers: ^2.1 +- cweagans/composer-patches: ^1.7.0 +- drupal/address: ^2.0 +- drupal/admin_toolbar: ^3.0.0 +- drupal/better_exposed_filters: ^7.0 +- drupal/ckeditor: ^1.0 +- drupal/cookies: ^1.2 +- drupal/core: ^10.1 +- drupal/core-composer-scaffold: ^10.1 +- drupal/do_username: ^2.0 +- drupal/field_permissions: ^1.0.0 +- drupal/fixed_block_content: ^1.1 +- drupal/flag: ^4.0 +- drupal/geocoder: ^4.0 +- drupal/geofield: ^1.0 +- drupal/gin: ^4.0.0@alpha +- drupal/google_tag: ^2.0 +- drupal/inline_entity_form: ^3.0 +- drupal/new_relic_rpm: ^2.0 +- drupal/raven: ^6.0 +- drupal/redis: ^1.4.0 +- drupal/select2: ^1.13 +- drupal/slack: ^1.2.0 +- drupal/social_auth: ^4.0 +- drupal/social_auth_google: ^4.0 +- drupal/stable: ^2.0 +- drupal/twig_tweak: ^3.1 +- drush/drush: ^13.0 +- geocoder-php/nominatim-provider: ^5.2 +- npm-asset/jquery-ui-touch-punch: ^0.2.3 +- oomphinc/composer-installers-extender: ^2.0 +- platformsh/config-reader: ^3.0.0 +- vlucas/phpdotenv: ^5.2 +**Composer Development Dependencies:** +- axelerant/db-docker: ^1.1 +- axelerant/drupal-quality-checker: ^1.4 +- behat/mink: ^1.10 +- behat/mink-browserkit-driver: ^2.1 +- phpunit/phpunit: ^9.0 +- symfony/browser-kit: ^7.0 +- weitzman/drupal-test-traits: ^2.0 + +--- + +**Original Source:** Project README \ No newline at end of file diff --git a/drupal-doc-gen/index02.js b/drupal-doc-gen/index02.js new file mode 100644 index 00000000..13854b71 --- /dev/null +++ b/drupal-doc-gen/index02.js @@ -0,0 +1,234 @@ +const fs = require('fs-extra'); +const path = require('path'); +const axios = require('axios'); +const crypto = require('crypto'); + +// Load environment variables +require('dotenv').config(); +console.log('Using API Key:', process.env.OPENROUTER_API_KEY ? '***' : 'Not found'); + +// Configuration +const API_BASE_URL = process.env.OPENROUTER_API_BASE_URL || 'https://openrouter.ai/api/v1/chat/completions'; +const API_KEY = process.env.OPENROUTER_API_KEY; +const MODEL = process.env.OPENROUTER_MODEL || 'google/gemini-2.0-flash-001'; +const CUSTOM_DIRS = [ + path.resolve(process.cwd(), '../web/modules/custom'), + path.resolve(process.cwd(), '../web/themes/custom') +]; +const OUTPUT_DIRS = { + 'Tutorial': 'docs1/tutorials', + 'How-To': 'docs1/how-to', + 'Reference': 'docs1/reference', + 'Explanation': 'docs1/explanation', + 'Index': 'docs1' +}; + +// Utility function to read files if they exist +function readFileIfExists(filePath) { + try { + return fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : ''; + } catch (error) { + console.error(`Error reading file ${filePath}:`, error.message); + return ''; + } +} + +// Recursively collect all README.md files +function collectReadmeFiles(directory) { + let readmeFiles = []; + function walk(dir) { + if (!fs.existsSync(dir)) { + console.warn(`Directory not found: ${dir}`); + return; + } + const files = fs.readdirSync(dir); + for (const file of files) { + const fullPath = path.join(dir, file); + if (file === 'node_modules' || file === 'vendor' || file === 'contrib') continue; + if (fs.statSync(fullPath).isDirectory()) walk(fullPath); + else if (file.toLowerCase() === 'readme.md') readmeFiles.push(fullPath); + } + } + walk(directory); + return readmeFiles; +} + +// Read and return the content of all README.md files +function readAllReadmeFiles() { + let readmeContents = []; + for (const dir of CUSTOM_DIRS) { + console.log(`Scanning directory: ${dir}`); + const readmeFiles = collectReadmeFiles(dir); + for (const readmeFile of readmeFiles) { + const content = readFileIfExists(readmeFile); + console.log(`Reading README: ${readmeFile} - Length: ${content.length}`); + readmeContents.push({ name: path.basename(path.dirname(readmeFile)), content }); + } + } + return readmeContents; +} + +// Read the root README.md and major configuration files (package.json, composer.json) +function readProjectFiles() { + const rootReadmePath = path.resolve(process.cwd(), '../README.md'); + const rootReadme = readFileIfExists(rootReadmePath); + const packageJsonPath = path.resolve(process.cwd(), '../package.json'); + const composerJsonPath = path.resolve(process.cwd(), '../composer.json'); + + const packageJson = readFileIfExists(packageJsonPath); + const composerJson = readFileIfExists(composerJsonPath); + + return { rootReadme, packageJson, composerJson }; +} + +// Enhanced prompt for AI to classify and generate structured documentation +async function classifyAndGenerateDocumentation(source) { + const truncatedContent = source.content.length > 2000 ? source.content.slice(0, 2000) + '... [truncated]' : source.content; + const prompt = `You are tasked with generating structured documentation using the Diátaxis framework for the provided project source: + +Source: ${source.name} + +Analyze the content and generate appropriate documentation under one of the following categories: Tutorial, How-To Guide, Reference, or Explanation. + +Format the response as follows: + +Category: [One of Tutorial, How-To, Reference, Explanation] +Title: [Title of the documentation] +Content: +[The structured content for this section] + +Project Content: +${truncatedContent}`; + + try { + const response = await axios.post( + API_BASE_URL, + { model: MODEL, messages: [{ role: 'user', content: prompt }] }, + { headers: { 'Authorization': `Bearer ${API_KEY}`, 'Content-Type': 'application/json' } } + ); + + const result = response.data.choices[0].message.content.trim(); + + const categoryMatch = result.match(/Category:\s*(.*)/i)?.[1]?.trim(); + const titleMatch = result.match(/Title:\s*(.*)/i)?.[1]?.trim(); + const contentMatch = result.split(/Content:/i)[1]?.trim(); + + if (categoryMatch && titleMatch && contentMatch) { + return { category: categoryMatch, title: titleMatch, content: contentMatch }; + } else { + throw new Error('Unexpected response format'); + } + } catch (error) { + console.error('Error generating documentation:', error.message); + return null; + } +} + +// Enhanced filename generator +function generateFileName(title, category) { + const sanitizedTitle = title.replace(/[^a-zA-Z0-9_-]/g, '_').toLowerCase(); + const hash = crypto.createHash('md5').update(title).digest('hex').slice(0, 6); + return `${sanitizedTitle}_${category.toLowerCase()}_${hash}.md`; +} + +// Generate the documentation index page +function generateIndexPage(documentationLinks) { + const intro = `# Project Documentation Index + +This is the main index page for the project documentation, organized using the Diátaxis framework. + +Navigate to the specific sections below for more details: +`; + const linksList = documentationLinks.map(({ category, title, fileName }) => `- **[${title} (${category})](${fileName})**`).join('\n'); + return `${intro} +${linksList}`; +} + +// Save content to the appropriate directory +function saveDocumentation(type, title, content) { + const targetDir = OUTPUT_DIRS[type] || OUTPUT_DIRS['Index']; + const fileName = generateFileName(title, type); + fs.outputFileSync(path.join(targetDir, fileName), content); + return fileName; +} + +// Extract dependencies or tools from package.json and composer.json +function extractDependencies(packageJsonContent, composerJsonContent) { + let dependencies = []; + + if (packageJsonContent) { + try { + const packageJson = JSON.parse(packageJsonContent); + dependencies.push('**NPM Dependencies:**'); + for (const [dep, version] of Object.entries(packageJson.dependencies || {})) { + dependencies.push(`- ${dep}: ${version}`); + } + dependencies.push('**Development Dependencies:**'); + for (const [dep, version] of Object.entries(packageJson.devDependencies || {})) { + dependencies.push(`- ${dep}: ${version}`); + } + } catch (error) { + console.error('Error parsing package.json:', error.message); + } + } + + if (composerJsonContent) { + try { + const composerJson = JSON.parse(composerJsonContent); + dependencies.push('**Composer Dependencies:**'); + for (const [dep, version] of Object.entries(composerJson.require || {})) { + dependencies.push(`- ${dep}: ${version}`); + } + dependencies.push('**Composer Development Dependencies:**'); + for (const [dep, version] of Object.entries(composerJson['require-dev'] || {})) { + dependencies.push(`- ${dep}: ${version}`); + } + } catch (error) { + console.error('Error parsing composer.json:', error.message); + } + } + + return dependencies.join('\n'); +} + +// Main function to generate structured documentation +async function generateDocumentation() { + const { rootReadme, packageJson, composerJson } = readProjectFiles(); + const contentSources = [ + { name: 'Project README', content: rootReadme }, + ...readAllReadmeFiles() + ]; + const dependenciesSummary = extractDependencies(packageJson, composerJson); + + let documentationLinks = []; + + for (const source of contentSources) { + const docResult = await classifyAndGenerateDocumentation(source); + if (docResult) { + const { category, title, content } = docResult; + const fullContent = `# ${title} + +${content} + +--- + +**Dependencies and Tools:** + +${dependenciesSummary} + +--- + +**Original Source:** ${source.name}`; + const fileName = saveDocumentation(category, title, fullContent); + documentationLinks.push({ category, title, fileName }); + } + } + + // Generate and save the index page + const indexPageContent = generateIndexPage(documentationLinks); + saveDocumentation('Index', 'index', indexPageContent); + + console.log('Documentation generation complete!'); +} + +generateDocumentation();