🦄 Automatically write docstrings for your code!🦄

This github action generates docstrings for your Python functions with the Ponicode AI engine (this action is currently in beta version)

- uses: ponicode/docstrings-action@master
  with:
    repo_path: ./
    all_repo: False

Once the docstrings are written, use the create pull request action to see the results in the branch of your choice

- name: Create Pull Request
  uses: peter-evans/create-pull-request@v2
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    commit-message: '[ponicode-pull-request] Ponicode found docstrings to write!'
    branch: ponicode-docstrings
    title: '[Ponicode] Docstrings created'
    body: |
        Ponicode report
        - Ponicode found docstrings to write
        - Auto-generated by Ponicode

Terms of use

By using this action, Ponicode will send the content of all the Python files of your project to the Ponicode API in order to provide you with relevant information.

How to setup

Create a yaml workflow file in your project

Go to the root of your project, and create the path to your workflow file. For example

mkdir -p .github/workflows

You can also just create a folder named .github, in it create another folder named workflows. You can now create a YAML file named ponicode.yml and copy one of the following example in it!

Here is an example of what to put in your .github/workflows/ponicode.yml file to trigger the action.

name: Ponicode docstrings generation

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with: 
        fetch-depth: 0
    - name: Get paths
      run: |
        git show --pretty="" --name-only ${{ github.sha }} > PATHS_TO_CHANGED_FILES.txt
    - uses: ponicode/docstrings-action@master
      with:
        repo_path: ./
        all_repo: True
      # Creates pull request with all changes in file
    - name: Create Pull Request 
      uses: peter-evans/create-pull-request@v2 
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        commit-message: '[ponicode-pull-request] Ponicode wrote new docstrings!'
        branch: ponicode-docstring
        title: '[Ponicode] Docstrings created'
        body: |
            Ponicode report
            - Ponicode found undocumented functions
            - Auto-generated by Ponicode

This yaml file writes docstrings on your undocumented Python functions everytime you push on master and makes a pull request on a ponicode-docstrings branch with the docstrings created

Ponicode Action inputs

Name	Description	Required	Default
repo_path	The relative path in your repo to the files you want Ponicode to test. By default, Ponicode tests your whole repo.	true	./
all_repo	Boolean. By default, the value is False. Choose if you want to write docstrings only on the files you just commited (False) or on all your repository (True)	true	False

Use cases:

Trigger Ponicode action on push on custom branch.

name: Ponicode docstrings generation

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ custom ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with: 
        fetch-depth: 0
    - name: Get paths
      run: |
        git show --pretty="" --name-only ${{ github.sha }} > PATHS_TO_CHANGED_FILES.txt
    - uses: ponicode/docstrings-action@master
      with:
        repo_path: ./
        all_repo: True
      # Creates pull request with all changes in file
    - name: Create Pull Request 
      uses: peter-evans/create-pull-request@v2 
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        commit-message: '[ponicode-pull-request] Ponicode wrote new docstrings!'
        branch: ponicode-docstring
        title: '[Ponicode] Docstrings created'
        body: |
            Ponicode report
            - Ponicode found undocumented functions!
            - Auto-generated by Ponicode

Trigger Ponicode action when you push on master or when you make a pull request on custom branch

name: Ponicode docstrings generation

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]
  pull_request:
    branches: [ custom ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with: 
        fetch-depth: 0
    - name: Get paths
      run: |
        git show --pretty="" --name-only ${{ github.sha }} > PATHS_TO_CHANGED_FILES.txt
    - uses: ponicode/docstrings-action@master
      with:
        repo_path: ./
        all_repo: True
      # Creates pull request with all changes in file
    - name: Create Pull Request 
      uses: peter-evans/create-pull-request@v2 
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        commit-message: '[ponicode-pull-request] Ponicode wrote new docstrings!'
        branch: ponicode-docstring
        title: '[Ponicode] Docstrings created'
        body: |
            Ponicode report
            - Ponicode found undocumented functions
            - Auto-generated by Ponicode

Trigger Ponicode action only on your last committed files (all_repo = False) when you push on master

name: Ponicode docstrings generation

# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the master branch
on:
  push:
    branches: [ master ]

# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
  # This workflow contains a single job called "build"
  build:
    # The type of runner that the job will run on
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
      with: 
        fetch-depth: 0
    - name: Get paths
      run: |
        git show --pretty="" --name-only ${{ github.sha }} > PATHS_TO_CHANGED_FILES.txt
    - uses: ponicode/docstrings-action@master
      with:
        repo_path: ./
        all_repo: False
      # Creates pull request with all changes in file
    - name: Create Pull Request 
      uses: peter-evans/create-pull-request@v2 
      with:
        token: ${{ secrets.GITHUB_TOKEN }}
        commit-message: '[ponicode-pull-request] Ponicode wrote new docstrings!'
        branch: ponicode-docstring
        title: '[Ponicode] Docstrings created'
        body: |
            Ponicode report
            - Ponicode found undocumented functions
            - Auto-generated by Ponicode           

Examples of generated docstrings

def add(a, b):
    """
    add two arguments .
    AI-generated by Ponicode.
    """
    return a + b

def reverse_words(input_str):
    """
    reverse string .
    AI-generated by Ponicode.
    """
    return " ".join(input_str.split()[::-1])

def determinant(matrix):
    """
    return the determines of a matrix .
    AI-generated by Ponicode.
    """
    if len(matrix) == 1:
        return matrix[0][0]

    return sum(
        x * determinant(minor(matrix, 0, i)) * (-1) ** i
        for i, x in enumerate(matrix[0])
    )

Contact us

We would love to have your feedbacks! Tell us what you love and what you want us to improve about this action at gaspard@ponicode.com.
We also have a slack community, where people can ask for help if they encounter problems with our products and where we keep you informed about our latest releases.
Join us here: https://ponicode-community.slack.com/join/shared_invite/zt-fiq4fhkg-DE~a_FkJ7xtiZxW7efyA4Q#/
If you want to know more about Ponicode and the different services we propose, you can check our website https://ponicode.com!