• Motivation
• Usage
  • Prerequisites
  • Adding the Action to Your Workflow
• Action Configuration
  • Environment Variables
  • Inputs
  • Features de/activation
  • Features configuration
  • Page generator options
• Action Outputs
• Project Setup
• Run unit test
• Deployment
• Features
  • Data Mining from GitHub Repositories
  • Data Mining from GitHub Projects
  • Living Documentation Page Generation
• Contribution Guidelines
• License Information
• Contact or Support Information

A tool designed to data-mine GitHub repositories for issues containing project documentation (e.g. tagged with feature-related labels). This tool automatically generates comprehensive living documentation in Markdown format, providing detailed feature overview pages and in-depth feature descriptions.

Addresses the need for continuously updated documentation accessible to all team members and stakeholders. Achieves this by extracting information directly from GitHub issues and integrating this functionality to deliver real-time, markdown-formatted output. Ensures everyone has the most current project details, fostering better communication and efficiency throughout development.

Before we begin, ensure you have a GitHub Token with permission to fetch repository data such as Issues and Pull Requests.

See the default action step definition:

- name: Generate Living Documentation
  id: generate_living_doc
  uses: AbsaOSS/[email protected]
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
  with:
    repositories: '[
      {
        "orgName": "fin-services",
        "repoName": "investment-app",
        "queryLabels": ["feature", "enhancement"]
      },
      {
        "orgName": "health-analytics",
        "repoName": "patient-data-analysis",
        "queryLabels": ["functionality"]
      },
      {
        "orgName": "open-source-initiative",
        "repoName": "community-driven-project",
        "queryLabels": ["improvement"]
      }
    ]'

See the full example of action step definition (in example are used non-default values):

- name: Generate Living Documentation
  id: generate_living_doc
  uses: AbsaOSS/[email protected]
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}  
  with:
    # features de/activation
    project-state-mining: true
    
    # features configuration
    projects-title-filter": ["Community Outreach Initiatives", "Health Data Analysis"]
    
    # page generator options
    milestones-as-chapters: true

    # inputs
    repositories: '[
      {
        "orgName": "fin-services",
        "repoName": "investment-app",
        "queryLabels": ["feature", "enhancement"]
      },
      {
        "orgName": "health-analytics",
        "repoName": "patient-data-analysis",
        "queryLabels": ["functionality"]
      },
      {
        "orgName": "open-source-initiative",
        "repoName": "community-driven-project",
        "queryLabels": ["improvement"]
      }
    ]'

Configure the action by customizing the following parameters based on your needs:

• GITHUB_TOKEN (required):
  • Description: Your GitHub token for authentication.
  • Usage: Store it as a secret and reference it in the workflow file using ${{ secrets.GITHUB_TOKEN }}.
  • Example:

    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

• repositories (required)
  • Description: A JSON string defining the repositories to be included in the documentation generation.
  • Usage: List each repository with its organization name, repository name, and query labels.
  • Example:

    with:
      repositories: '[
        {
          "orgName": "fin-services",
          "repoName": "investment-app",
          "queryLabels": ["feature", "enhancement"]
        },
        {
          "orgName": "health-analytics",
          "repoName": "patient-data-analysis",
          "queryLabels": ["functionality"]
        },
        {
          "orgName": "open-source-initiative",
          "repoName": "community-driven-project",
          "queryLabels": ["improvement"]
        }
      ]'

• project-state-mining (optional, default: true)
  • Description: Enables or disables the mining of project state data from GitHub Projects.
  • Usage: Set to false to deactivate.
  • Example:

    with:
      project-state-mining: false

• projects-title-filter (optional, default: [])
  • Description: Filters the projects by titles. Only projects with these titles will be considered.
  • Usage: Provide a list of project titles to filter.
  • Example:

    with:
      projects-title-filter: ["Community Outreach Initiatives", "Health Data Analysis"]

• milestones-as-chapters (optional, default: false)
  • Description: When set to true, milestones in the projects will be treated as chapters in the generated documentation.
  • Usage: Set to true to enable this feature.
  • Example:

    with:
      milestones-as-chapters: true

The Living Documentation Generator action provides a key output that allows users to locate and access the generated documentation easily. This output can be utilized in various ways within your CI/CD pipeline to ensure the documentation is effectively distributed and accessible.

• documentation-path
  • Description: This output provides the path to the directory where the generated living documentation files are stored.
  • Usage:

   - name: Generate Living Documentation
     id: generate_doc
     ... rest of the action definition ...
     
   - name: Output Documentation Path
     run: echo "Generated documentation path: ${{ steps.generate_doc.outputs.documentation-path }}"            

If you need to build the action locally, follow these steps:

node --version
python3 --version

npm install

npm run build

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

If you need to run the scripts locally, follow these steps:

Create the shell file in the root directory. We will use run_script.sh.

touch run_script.sh

Add the shebang line at the top of the sh script file.

#!/bin/sh

Set the configuration environment variables in the shell script following the structure below. Also make sure that the GITHUB_TOKEN is configured in your environment variables.

export GITHUB_TOKEN=$(printenv GITHUB_TOKEN)
export PROJECT_STATE_MINING="true"
export PROJECTS_TITLE_FILTER="[]"
export MILESTONES_AS_CHAPTERS="true"
export REPOSITORIES='[
            {
              "orgName": "OrgName",
              "repoName": "example-project",
              "queryLabels": ["feature", "bug"]
            }
          ]'

For running the whole GitHub action, add the following commands to the shell script:

cd src || exit 1

python3 controller.py --github-token "$GITHUB_TOKEN" \
            --project-state-mining "$PROJECT_STATE_MINING" \
            --projects-title-filter "$PROJECTS_TITLE_FILTER" \
            --milestones-as-chapters "$MILESTONES_AS_CHAPTERS" \
            --repositories "$REPOSITORIES"

cd .. || exit 1

For running just one script at the time, add the following commands to the shell script:

cd src || exit 1

python3 github_query_project_state.py

cd .. || exit 1

From the terminal that is in the root of this project, make the script executable:

chmod +x run_script.sh

./run_script.sh

TODO - check this chapter and update by latest state

pytest

pytest -v  # Verbose mode
pytest path/to/test_file.py  # Run specific test file

pytest --cov=../scripts

deactivate

After testing and ensuring that everything is functioning as expected, prepare your files for deployment:

git add action.yml dist/index.js  # Adjust paths as needed
git commit -m "Prepare GitHub Action for deployment"
git push

This project uses GitHub Actions for deployment draft creation. The deployment process is semi-automated by a workflow defined in .github/workflows/release_draft.yml.

• Trigger the workflow: The release_draft.yml workflow is triggered on workflow_dispatch.
• Create a new draft release: The workflow creates a new draft release in the repository.
• Finalize the release draft: Edit the draft release to add a title, description, and any other necessary details related to GitHub Action.
• Publish the release: Once the draft is ready, publish the release to make it available to the public.

This feature allows you to define which repositories should be included in the living documentation process. By specifying repositories, you can focus on the most relevant projects for your documentation needs.

• Default Behavior: By default, the action will include all repositories defined in the repositories input parameter. Each repository is defined with its organization name, repository name, and query labels.

This feature allows you to define which projects should be included in the living documentation process. By specifying projects, you can focus on the most relevant projects for your documentation needs.

• Default Behavior: By default, the action will include all projects defined in the repositories. This information is provided by the GitHub API.
• Non-default Example: Use available options to customize which projects are included in the documentation.
  • project-state-mining: false deactivates the mining of project state data from GitHub Projects. If set to false, project state data will not be included in the generated documentation and project related configuration options will be ignored.
  • projects-title-filter: ["Community Outreach Initiatives", "Health Data Analysis"] filters the projects by titles, including only projects with these titles.

The goal is to provide a straightforward view of all issues in a single table, making it easy to see the overall status and details of issues across repositories.

• Default Behavior: By default, the action generates a single table that lists all issues from the defined repositories.
• Non-default Example: Use available options to customize the output, such as grouping issues by milestone.
  • milestones-as-chapters: true controls whether milestones are treated as chapters in the generated documentation.

We welcome contributions to the Living Documentation Generator! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.

Before contributing, please review our contribution guidelines for more detailed information.

This project is licensed under the Apache License 2.0. It is a liberal license that allows you great freedom in using, modifying, and distributing this software, while also providing an express grant of patent rights from contributors to users.

For more details, see the LICENSE file in the repository.

If you need help with using or contributing to Living Documentation Generator Action, or if you have any questions or feedback, don't hesitate to reach out:

• Issue Tracker: For technical issues or feature requests, use the GitHub Issues page.
• Discussion Forum: For general questions and discussions, join our GitHub Discussions forum.