Key Scripts & Automation

Key Scripts & Automation

To ensure quality and maintainability, this project uses several automated scripts and workflows.

GitHub Actions (CI/CD)

Our continuous integration and deployment (CI/CD) pipeline is managed by GitHub Actions. The workflows are defined in the .github/workflows/ directory.

• deploy.yml (Build and Deploy):

  • Trigger: Runs on every push to the main branch.
  • Job: Builds the Jekyll site in a controlled environment and deploys the resulting static files to GitHub Pages. This gives us more control than the default GitHub Pages build process.

• lint-and-links.yml (Quality Checks):

  • Trigger: Runs on every pull request and on pushes to main.
  • Jobs:
    1. Markdown Linting: Checks all .md files for formatting consistency.
    2. Link Checking: Scans all files for internal and external links and verifies that they are not broken. This is critical for ensuring the Advisor tool functions correctly.

• generate-diagram.yml (Diagram Automation):

  • Trigger: Runs whenever a file is changed in the advisor/ directory or when the script itself (generate_diagram.py) is updated.
  • Job: Executes the generate_diagram.py script. If the script modifies advisor/advisor_diagram.md, this action automatically commits the changes back to the repository.

• spell-check.yml (Spell Checking):

  • Trigger: Runs on every pull request and on pushes to main.
  • Job: Checks for spelling errors in Markdown files to maintain professionalism and clarity.

Local Scripts

generate_diagram.py

• Purpose: To automatically create a visual representation of the logic flow within the /advisor/ tool.
• How it Works:
  1. The Python script iterates through every Markdown file in the /advisor/ directory.
  2. It uses regular expressions to find all internal links (e.g., [Link Text](./some-page.md)).
  3. It builds a list of all connections (e.g., start.md -> ownservice_intro.md).
  4. It then formats this list into a Mermaid.js graph definition.
  5. Finally, it overwrites the content of advisor/advisor_diagram.md with the new graph definition.
• How to Run Manually: If you make extensive changes to the Advisor and want to see the updated diagram locally before pushing, you can run the script from the root of the repository:

  python generate_diagram.py