Skip to content

Conversation

Copilot
Copy link
Contributor

@Copilot Copilot AI commented Sep 15, 2025

Thanks for assigning this issue to me. I'm starting to work on it and will keep this PR's description up to date as I form a plan and make progress.

Original issue description:

We would like to have automatic code style reviews and checks on code-cell blocks.

Code in MyST/Jupyter-Book projects are contained in code-cell directives, while code can also be contained in fenced directives -- for displaying code -- in standard markdown.

MyST example:

import numpy as np

and a standard markdown code block example

import numpy as np

I would like to build a github action code-style-checker that looks for these directives in the md files and run black over the contents to ensure code is formatted and styled correctly (in line with PEP8 -- for python). The language for each code-cell or markdown code-block highlight language should be checked to be python, python3, ipython, ipython3 as black is built to review python code. If a language such as julia is listed -- should output a message to the logs skipping the code-cell due to code not being labelled as python code.

How the action works:

  1. The action would run based on a comment in a PR comment box @quantecon-code-style
  2. find the list of changed markdown (md) files using an action such as tj-actions/changed-files@v40
  3. parse the markdown looking for python code
  4. run black over the code and commit the results back to the original file (each individual lecture markdown file should have its own black results commit with a commit message such as "[{{ filename }}] applying black changes to code" please)

The action should work directly on the markdown files such as lecture/aiyagari.md extracting code from the relevant code cells and code blocks.

Suggested workflow template:

name: Code Style Formatter
on:
  issue_comment:
    types: [created]

jobs:
  format-code:
    if: github.event.issue.pull_request && contains(github.event.comment.body, '@quantecon-code-style')
    runs-on: ubuntu-latest
    
    steps:
    - name: Checkout PR branch
      uses: actions/checkout@v4
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        ref: ${{ github.event.pull_request.head.ref }}
    
    - name: Get changed files
      id: changed-files
      uses: tj-actions/changed-files@v40
      with:
        files: '**/*.md'
    
    - name: Format MyST markdown files
      run: |
        # Your custom script to:
        # 1. Extract code blocks from changed .md files
        # 2. Run black on Python code blocks
        # 3. Update the files with formatted code
        
    - name: Commit changes
      run: |
        git config --local user.email "[email protected]"
        git config --local user.name "GitHub Action"
        git add .
        git diff --staged --quiet || git commit -m "Auto-format code blocks with black"
        git push

Configuration options:

  1. enabled to search for python code in MyST markdown elements (code-cell directives) (default = True)
  2. enabled to search for python code in standard markdown blocks (fenced code-block directives) (default = True)
  3. parse blocks with python, python3, ipython, ipython3 languages

Existing actions:

There is a black github action available, but it is expecting a code project in a src directory. This action will be different as it needs to apply black to code contained in a MyST markdown document.

Fixes #221.


💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more Copilot coding agent tips in the docs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

[code] code style checks (black)
2 participants