Fix gh-pages URL structure - copy docs to root level directories

Author: jgeluk

.github/workflows/gh-pages.yml

@@ -40,17 +40,33 @@ jobs:
 
       - name: Prepare Markdown documentation
         run: |
-          # Markdown files are already in the repository, no conversion needed
-          # GitHub Pages can serve Markdown files directly
-          echo "Markdown documentation files are ready for GitHub Pages"
-          # Add all Markdown files
-          find . -name "*.md" -exec git add -f {} \;
+          # Copy README files from src/ekglib/*/ to root-level directories
+          # This fixes the URL structure: files at concept_parser/README.md 
+          # will be served as https://ekgf.github.io/ekglib/concept_parser/
+          # instead of https://ekgf.github.io/ekglib/ekglib/concept_parser/
+          if [ -d "src/ekglib" ]; then
+            # Copy each subdirectory's README.md to root-level directory
+            find src/ekglib -type d -mindepth 1 -maxdepth 1 | while read -r dir; do
+              dirname=$(basename "$dir")
+              if [ -f "$dir/README.md" ]; then
+                mkdir -p "$dirname"
+                # Copy and fix relative links: ../../ becomes ../ (one level up to root)
+                sed 's|\[ekglib\](\.\./\.\./)|[ekglib](../)|g' "$dir/README.md" > "$dirname/README.md"
+              fi
+            done
+          fi
+          # Add root README.md and LICENSE
+          git add -f README.md LICENSE 2>/dev/null || true
+          # Add all the module directories that were copied
+          find . -maxdepth 1 -type d \( -name "*_parser" -o -name "*_export" -o -name "dataops_*" -o -name "maturity_model_parser" -o -name "step_export" \) -exec git add -f {} \; 2>/dev/null || true
         shell: bash
 
       - name: Remove irrelevant files from gh-pages branch
         run: |
           git rm --quiet -rf .github/ .idea/ .vscode/ .actrc .tool-versions *.sh *.code-workspace *.iml 2>/dev/null || true
+          git rm --quiet -rf src/ tests/ dist/ .venv/ ekglib.egg-info/ junit/ 2>/dev/null || true
           find . -name '*.py' -exec git rm --quiet --force {} \; 2>/dev/null || true
+          find . -name '__pycache__' -type d -exec git rm --quiet -rf {} \; 2>/dev/null || true
         shell: bash
 
       - name: Showing contents of gh-pages branch when running locally

README.md

@@ -23,37 +23,76 @@ A Python Library for various tasks in an EKG DataOps operation.
 
 ## Metadata Parsers
 
-- [Concept Parser](ekglib/concept_parser/)
-- [Persona Parser](ekglib/persona_parser/)
-- [Story Validate Rule Parser](ekglib/dataops_rule_parser/)
-- [Story Vaidate Rules Capture](ekglib/dataops_rules_capture/)
-- [Story Validate Rules Executor](ekglib/dataops_rules_execute/)
-- [Use Case Parser](ekglib/use_case_parser/)
-- [User Story Parser](ekglib/user_story_parser/)
+- [Concept Parser](concept_parser/)
+- [Persona Parser](persona_parser/)
+- [Story Validate Rule Parser](dataops_rule_parser/)
+- [Story Vaidate Rules Capture](dataops_rules_capture/)
+- [Story Validate Rules Executor](dataops_rules_execute/)
+- [Use Case Parser](use_case_parser/)
+- [User Story Parser](user_story_parser/)
 
 ## Capture Steps
 
-- [Xlsx Parser](ekglib/xlsx_parser/)
-- [LDAP Parser](ekglib/ldap_parser/)
+- [Xlsx Parser](xlsx_parser/)
+- [LDAP Parser](ldap_parser/)
 
 ---
 
 ## Installation
 
+**Using `uv` (recommended)**
+
+If you are using `uv` to manage your project, add `ekglib` as a dependency:
+
+```bash
+uv add ekglib
+```
+
+You can then run the provided CLI tools via `uv`:
+
+```bash
+uv run xlsx-parser --help
+uv run user-story-parser --help
+uv run pipeline-example --help
+```
+
+To install the CLI tools as global commands (similar to `pipx`):
+
+```bash
+uv tool install ekglib
+
+xlsx-parser --help
+user-story-parser --help
+pipeline-example --help
+```
+
+**Using `pip`**
+
+If you prefer to use `pip` directly:
+
 ```bash
-./setup.sh
+python -m pip install ekglib
 ```
 
-<details>
-<summary>⚠️ Troubleshooting: Python3 not linked</summary>
+The console scripts will then be available on your `PATH`:
+
+```bash
+xlsx-parser --help
+user-story-parser --help
+pipeline-example --help
+```
+
+---
+
+## Development setup (from source)
 
-If `python3` was not linked, run:
+If you cloned this repository and want to work on `ekglib` itself:
 
 ```bash
-brew link --overwrite python
+uv sync
 ```
 
-</details>
+This will create and populate a virtual environment using `uv` based on `pyproject.toml`.
 
 ---
 
@@ -62,13 +101,13 @@ brew link --overwrite python
 To run all tests:
 
 ```bash
-./run-tests.sh
+uv run pytest
 ```
 
 To run a single test:
 
 ```bash
-./run-tests.sh <name of test>
+uv run pytest tests/<path-to-test> -k <name-of-test>
 ```
 
 ---