Living Documentation Collector for GitHub

• Motivation
• Data-Mining Modes
• Usage
  • Prerequisites
  • Adding the Action to Your Workflow
• Action Configuration
  • Environment Variables
  • Inputs
    • Base Inputs
    • Mode Inputs
• Action Outputs
• How-to
  • How to Create a Token with Required Scope
  • How to Store Token as a Secret
• Contribution Guidelines
  • License Information
  • Contact or Support Information

Motivation

Addresses the need for continuously updated documentation accessible to all team members and stakeholders. Achieves this by extracting information directly from GitHub and providing it in a json format, which can be easily transformed into various documentation formats. This approach ensures that the documentation is always up-to-date and relevant, reducing the burden of manual updates and improving overall project transparency.

---

Data-Mining Modes

This Collector supports multiple mining modes, each with its own unique functionality. Read more about the modes at their respective links:

• Documentation Issues
• Test Catalog
• Test Headers
• Code Tags
• Release Notes
• Workflows
• User Guide

---

Usage

Prerequisites

Before we begin, ensure you have fulfilled the following prerequisites:

• GitHub Token with permission to fetch repository data such as Issues and Pull Requests.
• Python version 3.12 or higher.

Adding the Action to Your Workflow

See the default action step definition:

- name: Living Documentation Collector for GitHub
  id: living_doc_collector_gh
  uses: AbsaOSS/[email protected]
  env:
    GITHUB-TOKEN: ${{ secrets.REPOSITORIES_ACCESS_TOKEN }}  
  with:
    # modes de/activation
    doc-issues: false
    tests: false
    test-headers: false
    code-tags: false
    release-notes: false
    workflows: false
    user-guide: false

See the default action step definitions for each mode:

• Documentation Issues mode default step definition
• Tests mode default step definition
• Test Headers mode default step definition
• Code Tags mode default step definition
• Release Notes mode default step definition
• Workflows mode default step definition
• User Guide mode default step definition

Full Example of Action Step Definition

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

- name: Living Documentation Collector for GitHub
  id: living_doc_collector_gh
  uses: AbsaOSS/[email protected]
  env:
    GITHUB-TOKEN: ${{ secrets.REPOSITORIES_ACCESS_TOKEN }}  
  with:
    doc-issues: true                       # Documentation Issues mode de/activation
    verbose-logging: true                  # Optional: project verbose (debug) logging feature de/activation
    
    # 'Documentation Issues' mode required configuration
    doc-issues-repositories: |
        [
          {
            "organization-name": "your-organization-name",
            "repository-name": "your-project-living-documentation",
            "projects-title-filter": []
          },
          {
            "organization-name": "your-organization-name",
            "repository-name": "your-another-project-living-documentation",
            "projects-title-filter": ["Management Overview"]
          }
        ]
      
    # 'Documentation Issues' mode optional configuration
    doc-issues-project-state-mining: true     # project state mining feature de/activation

---

Action Configuration

This section outlines the essential parameters that are common to all modes a user can define. Configure the action by customizing the following parameters based on your needs:

Environment Variables

Variable Name	Description	Required	Usage
REPOSITORIES_ACCESS_TOKEN	GitHub access token for authentication, that has permission to access all defined repositories / projects.	Yes	Store it in the GitHub repository secrets and reference it in the workflow file using ${{ secrets.REPOSITORIES_ACCESS_TOKEN }}.

• Example:

  env:
    GITHUB-TOKEN: ${{ secrets.REPOSITORIES_ACCESS_TOKEN }}

The way how to generate and store a token into the GitHub repository secrets is described in the support chapter.

Inputs

Base Inputs

These inputs are common to all modes.

Input Name	Description	Required	Default	Usage
doc-issues	Enables or disables Documentation Issues mode.	No	false	Set to true to activate.
tests	Enables or disables Tests mode.	No	false	Set to true to activate.
test-headers	Enables or disables Test headers mode.	No	false	Set to true to activate.
code-tags	Enables or disables Code tags mode.	No	false	Set to true to activate.
release-notes	Enables or disables Release Notes mode.	No	false	Set to true to activate.
workflows	Enables or disables Workflows mode.	No	false	Set to true to activate.
user-guide	Enables or disables User guide mode.	No	false	Set to true to activate.
verbose-logging	Enables or disables verbose (debug) logging.	No	false	Set to true to activate.

Example

with:
  doc-issues: true          # Activation of Documentation Issues mode
  test-headers: true        # Activation of Test Headers mode
  
  verbose-logging: true     # Activation of verbose (debug) logging

Mode Inputs

Mode-specific inputs and outputs are detailed in the respective mode's documentation:

• Documentation Issues mode specific inputs
• Tests mode specific inputs
• Test Headers mode specific inputs
• Code Tags mode specific inputs
• Release Notes mode specific inputs
• Workflows mode specific inputs
• User Guide mode specific inputs

---

Action Outputs

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

• output-path
  • Description: The root output path to the directory where all generated living documentation files are stored.
  • Usage:

   - name: Living Documentation Collector for GitHub
     id: living_doc_collector_gh
     ... rest of the action definition ...
     
   - name: Output Documentation Path
     run: echo "GitHub Collector root output path: ${{ steps.living_doc_collector_gh.outputs.output-path }}"            

Each mode generates its output files, which is stored in the output-path directory with clear naming conventions.

---

Developer Guide

See this Developer Guide for more technical, development-related information.

---

How-to

This section aims to help the user walk through different processes, such as:

• Generating and storing a token as a secret

How to Create a Token with Required Scope

1. Go to your GitHub account settings.
2. Click on the Developer settings tab in the left sidebar.
3. In the left sidebar, click on Personal access tokens and choose Tokens (classic).
4. Click on the Generate new token button and choose Generate new token (classic).
5. Optional - Add a note detailing what the token is for and choose the token expiration date.
6. Select ONLY bold scope options below:
   • workflow
   • write:packages
     • read:packages
   • admin:org
     • read:org
     • manage_runners:org
   • admin:public_key
     • read:public_key
   • admin:repo_hook
     • read:repo_hook
   • admin:enterprise
     • manage_runners:enterprise
     • read:enterprise
   • audit_log
     • read:audit_log
   • project
     • read:project
7. Copy the token value somewhere safe, because you won't be able to view it again.
8. Authorize the new token for the organization you want to fetch from.

How to Store Token as a Secret

1. Go to the GitHub repository, from which you want to run the GitHub Action.
2. Click on the Settings tab in the top bar.
3. In the left sidebar, click on Secrets and variables > Actions.
4. Click on the New repository secret button.
5. Name the token REPOSITORIES_ACCESS_TOKEN and paste the token value.

---

Contribution Guidelines

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

How to Contribute

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

License 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.

Contact or Support Information

If you need help with using or contributing to the 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.