Feature/75 fixing the overall bugs based on a observation (#76)

- Updating documentation to the current logic.
AbsaOSS · Dec 12, 2024 · 8b8da09 · 8b8da09
1 parent 7ae023a
commit 8b8da09
Show file tree

Hide file tree

Showing 4 changed files with 125 additions and 117 deletions.
diff --git a/README.md b/README.md
@@ -29,7 +29,7 @@
 
 ## Motivation
 
-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.
+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, mdoc viewer capable formatted output. Ensures everyone has the most current project details, fostering better communication and efficiency throughout development.
 
 ---
 ## Mining Regimes
@@ -78,26 +78,27 @@ See the full example of action step definition (in example are used non-default
     verbose-logging: true                  # project verbose (debug) logging feature de/activation
 
     # LivDoc Regime configuration
-    liv-doc-repositories: '[
-      {
-        "organization-name": "fin-services",
-        "repository-name": "investment-app",
-        "query-labels": ["feature", "enhancement"],
-        "projects-title-filter": []
-      },
-      {
-        "organization-name": "health-analytics",
-        "repository-name": "patient-data-analysis",
-        "query-labels": ["functionality"],
-        "projects-title-filter": ["Health Data Analysis Project"]
-      },
-      {
-        "organization-name": "open-source-initiative",
-        "repository-name": "community-driven-project",
-        "query-labels": ["improvement"],
-        "projects-title-filter": ["Community Outreach Initiatives", "CDD Project"] 
-      }
-    ]'
+    liv-doc-repositories: |
+        [
+          {
+            "organization-name": "fin-services",
+            "repository-name": "investment-app",
+            "query-labels": ["feature", "enhancement"],
+            "projects-title-filter": []
+          },
+          {
+            "organization-name": "health-analytics",
+            "repository-name": "patient-data-analysis",
+            "query-labels": ["functionality"],
+            "projects-title-filter": ["Health Data Analysis Project"]
+          },
+          {
+            "organization-name": "open-source-initiative",
+            "repository-name": "community-driven-project",
+            "query-labels": ["improvement"],
+            "projects-title-filter": ["Community Outreach Initiatives", "CDD Project"] 
+          }
+        ]
     liv-doc-project-state-mining: true     # project state mining feature de/activation
     liv-doc-structured-output: true        # structured output feature de/activation
     liv-doc-group-output-by-topics: true   # group output by topics feature de/activation
@@ -235,11 +236,7 @@ export INPUT_LIV_DOC_GROUP_OUTPUT_BY_TOPICS=true
 
 For running the GitHub action incorporate these commands into the shell script and save it.
 ```
-cd src || exit 1
-
 python3 main.py
-
-cd .. || exit 1
 ```
 
 ### Make the Script Executable

diff --git a/living_documentation_regime/README.md b/living_documentation_regime/README.md
@@ -17,7 +17,7 @@
     - [Structured Output](#structured-output)
     - [Output Grouped by Topics](#output-grouped-by-topics)
 
-This regime is designed to data-mine GitHub repositories for [documentation tickets](#documentation-ticket-introduction) 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.
+This regime is designed to data-mine GitHub repositories for [documentation tickets](#documentation-ticket-introduction) containing project documentation (e.g. tagged with feature-related labels). This tool automatically generates comprehensive living documentation in a format compatible with an [mdoc viewer](https://github.com/AbsaOSS/cps-mdoc-viewer), providing detailed feature overview pages and in-depth feature descriptions.
 
 ## Regime De/Activation
 
@@ -43,26 +43,21 @@ See the default minimal Living Documentation regime action step definition:
     GITHUB-TOKEN: ${{ secrets.REPOSITORIES_ACCESS_TOKEN }}  
   with:
     liv-doc-regime: true                   # living documentation regime de/activation  
-    liv-doc-repositories: '[
-      {
-        "organization-name": "fin-services",
-        "repository-name": "investment-app",
-        "query-labels": ["feature", "enhancement"],
-        "projects-title-filter": []
-      },
-      {
-        "organization-name": "health-analytics",
-        "repository-name": "patient-data-analysis",
-        "query-labels": ["functionality"],
-        "projects-title-filter": ["Health Data Analysis Project"]
-      },
-      {
-        "organization-name": "open-source-initiative",
-        "repository-name": "community-driven-project",
-        "query-labels": ["improvement"],
-        "projects-title-filter": ["Community Outreach Initiatives", "CDD Project"]
-      }
-    ]'
+    liv-doc-repositories: |
+        [
+          {
+            "organization-name": "fin-services",
+            "repository-name": "investment-app",
+            "query-labels": ["feature", "enhancement"],
+            "projects-title-filter": []
+          },
+          {
+            "organization-name": "health-analytics",
+            "repository-name": "patient-data-analysis",
+            "query-labels": ["functionality"],
+            "projects-title-filter": ["Health Data Analysis Project"]
+          }
+        ]
 ```
 
 See the full example of Living Documentation regime step definition (in example are used non-default values):
@@ -76,27 +71,22 @@ See the full example of Living Documentation regime step definition (in example
   with:
     liv-doc-regime: true                   # living documentation regime de/activation
     verbose-logging: true                  # project verbose (debug) logging feature de/activation
-
-    liv-doc-repositories: '[
-      {
-        "organization-name": "fin-services",
-        "repository-name": "investment-app",
-        "query-labels": ["feature", "enhancement"],
-        "projects-title-filter": []
-      },
-      {
-        "organization-name": "health-analytics",
-        "repository-name": "patient-data-analysis",
-        "query-labels": ["functionality"],
-        "projects-title-filter": ["Health Data Analysis Project"]
-      },
-      {
-        "organization-name": "open-source-initiative",
-        "repository-name": "community-driven-project",
-        "query-labels": ["improvement"],
-        "projects-title-filter": ["Community Outreach Initiatives", "CDD Project"] 
-      }
-    ]'
+
+    liv-doc-repositories: |
+        [
+          {
+            "organization-name": "fin-services",
+            "repository-name": "investment-app",
+            "query-labels": ["feature", "enhancement"],
+            "projects-title-filter": []
+          },
+          {
+            "organization-name": "health-analytics",
+            "repository-name": "patient-data-analysis",
+            "query-labels": ["functionality"],
+            "projects-title-filter": ["Health Data Analysis Project"]
+          }
+        ]
     liv-doc-project-state-mining: true     # project state mining feature de/activation
     liv-doc-structured-output: true        # structured output feature de/activation
     liv-doc-group-output-by-topics: true   # group output by topics feature de/activation
@@ -114,26 +104,21 @@ Configure the Living Documentation regime by customizing the following parameter
   - **Example**:
     ```yaml
     with:
-      liv-doc-repositories: '[
-      {
-        "organization-name": "fin-services",
-        "repository-name": "investment-app",
-        "query-labels": ["feature", "enhancement"],
-        "projects-title-filter": []
-      },
-      {
-        "organization-name": "health-analytics",
-        "repository-name": "patient-data-analysis",
-        "query-labels": ["functionality"],
-        "projects-title-filter": ["Health Data Analysis Project"]
-      },
-      {
-        "organization-name": "open-source-initiative",
-        "repository-name": "community-driven-project",
-        "query-labels": ["improvement"],
-        "projects-title-filter": ["Community Outreach Initiatives", "CDD Project"] 
-      }
-    ]'
+      liv-doc-repositories: |
+        [
+          {
+            "organization-name": "fin-services",
+            "repository-name": "investment-app",
+            "query-labels": ["feature", "enhancement"],
+            "projects-title-filter": []
+          },
+          {
+            "organization-name": "open-source-initiative",
+            "repository-name": "community-driven-project",
+            "query-labels": ["improvement"],
+            "projects-title-filter": ["Community Outreach Initiatives", "CDD Project"] 
+          }
+        ]
     ```
 
 - **liv-doc-project-state-mining** (optional, `default: false`)
@@ -170,23 +155,37 @@ Configure the Living Documentation regime by customizing the following parameter
 ## Expected Output
 
 The Living Documentation Generator in Living Documentation regime is designed to produce an Issue Summary page (index.md) along with multiple detailed single issue pages.
+The structure of pages is designed to work with the AbsaOSS [mdoc viewer](https://github.com/AbsaOSS/cps-mdoc-viewer) solution.
 
 ### Index Page Example
 
 ```markdown
-# Issue Summary page
+---
+title: Features
+toolbar_title: Features
+description_title: Living Documentation
+description: >
+  This is a comprehensive list and brief overview of all mined features.
+date: 2024-12-12
+weight: 0
+---
+
+<h1>Feature Summary page</h1>
+
+Our project is designed with a myriad of features to ensure seamless user experience, top-tier functionality, and efficient operations. Here, you'll find a summarized list of all these features, their brief descriptions, and links to their detailed documentation.
 
-Our project is designed with a myriad of issues to ensure seamless user experience, top-tier functionality, and efficient operations.
-Here, you'll find a summarized list of all these issues, their brief descriptions, and links to their detailed documentation.
+<h2>Feature Overview</h2>
 
-## Issue Overview
+<div class="cps-table sortable searchable filterableByColumns paginator">
 
-| Organization name| Repository name            | Issue 'Number - Title'         | Linked to project | Project Status | Issue URL  |
-|------------------|----------------------------|--------------------------------|-------------------|----------------|------------|
-| AbsaOSS          | living-doc-example-project | [#89 - Test issue 2](89_test_issue_2.md)      | 🔴 | ---            |[GitHub](#) |
-| AbsaOSS          | living-doc-example-project | [#88 - Test issue](88_test_issue.md)          | 🟢 | Todo           |[GitHub](#) |
-| AbsaOSS          | living-doc-example-project | [#41 - Initial commit.](41_initial_commit.md) | 🟢 | Done           |[GitHub](#) |
-| AbsaOSS          | living-doc-example-project | [#33 - Example bugfix](33_example_bugfix.md)  | 🔴 | ---            |[GitHub](#) |
+| Organization name | Repository name            | Issue 'Number - Title'              | Linked to project  | Project Status | Issue URL                                   |
+|-------------------|----------------------------|-------------------------------------|--------------------|----------------|---------------------------------------------|
+| AbsaOSS           | living-doc-example-project | [#89 - Test issue 2](features#test-issue-2)         | 🔴 | ---            | <a href='#' target='_blank'>GitHub link</a> |
+| AbsaOSS           | living-doc-example-project | [#88 - Test issue](features#test-issue.md)          | 🟢 | Todo           | <a href='#' target='_blank'>GitHub link</a> |
+| AbsaOSS           | living-doc-example-project | [#41 - Initial commit.](features#initial-commit.md) | 🟢 | Done           | <a href='#' target='_blank'>GitHub link</a> |
+| AbsaOSS           | living-doc-example-project | [#33 - Example bugfix](features#example-bugfix.md)  | 🔴 | ---            | <a href='#' target='_blank'>GitHub link</a> |
+
+</div>
 ```
 
 - **Project Status** can have various values depending on the project, such as: Todo, Done, Closed, In Progress, In Review, Blocked, etc. 
@@ -196,28 +195,35 @@ These values can vary from project to project.
 ### Issue Page Example
 
 ```markdown
-# FEAT: Advanced Book Search
-| Attribute         | Content                               |
-|-------------------|---------------------------------------|
-| Organization name | AbsaOSS                               |
-| Repository name   | living-doc-example-project            |
-| Issue number      | 17                                    |
-| State             | open                                  |
-| Issue URL         | [GitHub link](#)                      |
-| Created at        | 2023-12-12 11:34:52                   |
-| Updated at        | 2023-12-13 10:24:58                   |
-| Closed at         | None                                  |
-| Labels            | feature                               |
-| Project title     | Book Store Living Doc Example project |
-| Status            | Todo                                  |
-| Priority          | P1                                    |
-| Size              | S                                     |
-| MoSCoW            | N/A                                   |
-
-## Issue Content
+---
+title: "Advanced Book Search"
+date: 2024-12-12
+weight: 1
+---
+
+| Attribute         | Content                                     |
+|-------------------|---------------------------------------------|
+| Organization name | AbsaOSS                                     |
+| Repository name   | living-doc-example-project                  |
+| Issue number      | 17                                          |
+| Title             | Advanced Book Search                        |
+| State             | open                                        |
+| Issue URL         | <a href='#' target='_blank'>GitHub link</a> |
+| Created at        | 2023-12-12 11:34:52                         |
+| Updated at        | 2023-12-13 10:24:58                         |
+| Closed at         | None                                        |
+| Labels            | feature                                     |
+| Project title     | Book Store Living Doc Example project       |
+| Status            | Todo                                        |
+| Priority          | P1                                          |
+| Size              | S                                           |
+| MoSCoW            | ---                                         |
+
+<h3>Issue Content</h3>
+
 Users often struggle to find specific books in a large catalog. An advanced search feature would streamline this process, enhancing user experience.
 
-### Background
+#### Background
 ...
 ```
 

diff --git a/living_documentation_regime/living_documentation_generator.py b/living_documentation_regime/living_documentation_generator.py
@@ -579,6 +579,7 @@ def _generate_issue_summary_table(consolidated_issue: ConsolidatedIssue) -> str:
             "Organization name",
             "Repository name",
             "Issue number",
+            "Title",
             "State",
             "Issue URL",
             "Created at",
@@ -592,6 +593,7 @@ def _generate_issue_summary_table(consolidated_issue: ConsolidatedIssue) -> str:
             consolidated_issue.organization_name,
             consolidated_issue.repository_name,
             consolidated_issue.number,
+            consolidated_issue.title,
             consolidated_issue.state.lower(),
             issue_url,
             consolidated_issue.created_at,

diff --git a/tests/living_documentation_regime/test_living_documentation_generator.py b/tests/living_documentation_regime/test_living_documentation_generator.py
@@ -1019,6 +1019,7 @@ def test_generate_issue_summary_table_without_project_state_mining(
         "| Organization name | TestOrg |\n"
         "| Repository name | TestRepo |\n"
         "| Issue number | 42 |\n"
+        "| Title | Sample Issue |\n"
         "| State | open |\n"
         "| Issue URL | <a href='https://github.com/TestOrg/TestRepo/issues/42' target='_blank'>GitHub link</a>  |\n"
         "| Created at | 2024-01-01T00:00:00Z |\n"
@@ -1049,6 +1050,7 @@ def test_generate_issue_summary_table_with_project_state_mining_and_multiple_pro
         "| Organization name | TestOrg |\n"
         "| Repository name | TestRepo |\n"
         "| Issue number | 42 |\n"
+        "| Title | Sample Issue |\n"
         "| State | open |\n"
         "| Issue URL | <a href='https://github.com/TestOrg/TestRepo/issues/42' target='_blank'>GitHub link</a>  |\n"
         "| Created at | 2024-01-01T00:00:00Z |\n"
@@ -1090,6 +1092,7 @@ def test_generate_issue_summary_table_with_project_state_mining_but_no_linked_pr
         "| Organization name | TestOrg |\n"
         "| Repository name | TestRepo |\n"
         "| Issue number | 42 |\n"
+        "| Title | Sample Issue |\n"
         "| State | open |\n"
         "| Issue URL | <a href='https://github.com/TestOrg/TestRepo/issues/42' target='_blank'>GitHub link</a>  |\n"
         "| Created at | 2024-01-01T00:00:00Z |\n"