Action To Use Quarto For README Generation

[AFg6K7h4fhy2]

For the scope of this PR, refer to issue #19 .

[AFg6K7h4fhy2]

@dylanhmorris I would appreciate some guidance on the correct format of the following workflow:

• https://github.com/CDCgov/forecasttools-py/pull/49/files#diff-e4a6b66cdb8f46bc35fa2d206adad3e1241f2064aacf427f28094b0ec892158d

[AFg6K7h4fhy2]

At present, the README renders with this as the yaml:

The YAML

name: Render Quarto README

on:
  push:
    paths:
      - README.qmd

jobs:
  render-readme:
    runs-on: ubuntu-latest

    steps:
    - name: Checkout Repository
      uses: actions/checkout@v4

    - name: Set up Python
      uses: actions/setup-python@v5
      with:
        python-version: "3.12"

    - name: Set Up Quarto
      uses: quarto-dev/quarto-actions/setup@v2

    - name: Install Poetry
      run: pip install poetry

    - name: Install Dependencies With Poetry
      run: poetry install --with dev

    - name: Set QUARTO_PYTHON to Poetry Environment
      run: echo "QUARTO_PYTHON=$(poetry env info --path)/bin/python" >> $GITHUB_ENV

    - name: Render README.md From README.qmd
      run: quarto render README.qmd

    - name: Commit And Push Changes
      run: |
        git config --global user.name "github-actions[bot]"
        git config --global user.email "github-actions[bot]@users.noreply.github.com"
        git add README.md README.qmd || echo "Nothing to commit"
        git commit -m "Auto-update README.md" || echo "No changes to commit"
        git push || echo "No changes to commit"
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

However, there is a minor formatting issue:

<style> .dataframe > thead > tr, .dataframe > tbody > tr { text-align: right; white-space: pre-wrap; } </style> shape: (81_713, 3)

[dylanhmorris]

If you're going to have this on every push that modifies README.qmd, regardless of branch, should it definitely be a github action and not a pre-commit hook? @AFg6K7h4fhy2, cc @damonbayer @gvegayon

[AFg6K7h4fhy2]

Re: #49 (comment)

I am not sure here and will defer to whatever is decided by you and those who are tagged.

Since I do not expect the README.qmd to be updated very often and since I have a vague notion that "server side rendering" is "more robust", I opted for GitHub Actions. That this could be a pre-commit hook did occur to me, but the aforementioned and the belief that I'd be able to implement an action quicker steered me away from this path.

[dylanhmorris]

The downside of server-side is that it adds additional commits and means that the local repo doesn't necessarily reflect what's being pushed (without an additional pull). Given that any reasonable dev environment for editing the readme should be able to render it, I don't really see server side rendering as "more robust" in this case.

[dylanhmorris]

The downside of server-side is that it adds additional commits, and means that the local repo doesn't necessarily reflect what's being pushed (without an additional pull). Given that any reasonable dev environment for editing the readme should be able to render it, I don't really see server side rendering as "more robust" in this case.

The one thing that will be less "just works" with client-side rendering is editing the README.qmd in the web gui. But that arguably should not be done anyway.

[AFg6K7h4fhy2]

The additional commits & pull are arguments enough for me. I will wait for another hour or so for comments, working on other entities in forecasttools-py, before proceeding with a shift to pre-commit.

[AFg6K7h4fhy2]

I forgot to add a tentative utilities diagram here. I will refine and add the contents of #16 to the README.

[AFg6K7h4fhy2]

Order of operations:

• Updated pre-commit.yaml in ./.github/workflows/ to have more recent versions.
• Updated .pre-commit-config.yaml with sections.
• Ran pre-commit autoupdate.
• Create ./scripts/ and render-quarto-readme.sh within.
• Ran chmod +x render-quarto-readme.sh in ./scripts/hooks/ after creation.
• Update .pre-commit-config.yaml to have local hook.
• Ran pre-commit install.
• Ran pre-commit run --all-files.