Sample Programs Docs Generator 2.3.0 Features How To Python README Automation

With my free time this summer, I decided to take some time to automate yet more documentation for one of my repositories. Specifically, I have now automated the How to Python repo’s main README.

Table of Contents

• What Is How to Python README Automation?
• What Does How to Python README Automation Do?
• Future Plans

What Is How to Python README Automation?

Some time awhile back, I was asked to store all of the code from my How to Python series in a GitHub repo. Unfortunately, this fell pretty low on my list of priorities, so I relied a bit on the community to manage it—mainly Muhimen123.

Recently, I had some free time, so I figured I’d give the repo an overhaul. In particular, I thought it would be a good time to just clean things up. For instance, I had a lot of missing articles from the main README.

As always, in the process of doing these sort of monotonous data entry tasks, I decided it was time to do some automation. Specifically, I thought “what if I could completely generate the main README table automatically?” After all, I had done that several times before for other repos. That’s the focus of today’s update!

What Does How to Python README Automation Do?

If you head over to the How To Python repo, you’ll be greeted with a table of every article from the series. In this table, you’ll find links to related videos, challenges, and notebooks—if they exist.

Part of the automation process was making sure that these rows would be generated with all of the proper links. For example, if an article has an associated video, the video would be properly linked in the “video” column. A similar process was followed for the “challenge” and “notebook” columns.

To accomplish this, I created a new file called “how_to.py” which features the following function:

def _build_readme(self):
    self.page = MarkdownPage("README")

    # Introduction
    self.page.add_content("# How to Python - Source Code")
    self.page.add_section_break()
    self.page.add_content(get_intro_text())
    self.page.add_section_break()

    # Article List
    self.page.add_table_header("Index", "Title", "Publish Date", "Article", "Video", "Challenge", "Notebook")
    self.build_table()

Without getting into the details, this function generates the README page which we use to generate the README.md file. Of course, this code doesn’t perform the automation on its own. We run it using GitHub Actions every time a change is made to the main branch of the repo and once every Friday:

name: Deploy

on:
  push:
    branches: [ main ]
  schedule:
    - cron: '0 16 * * FRI'

jobs:
  build:

    runs-on: ubuntu-latest

    steps:
    - name: Checkout repo 
      uses: actions/checkout@v2
        
    - name: Set up Python 3.9
      uses: actions/setup-python@v2
      with:
        python-version: 3.9
        
    - name: Download docs generator
      run: |
        pip install --no-cache-dir generate_docs
        pip show generate_docs
        
    - name: Generate README
      run: |
        wikih
    - name: Commit wiki
      continue-on-error: true
      run: |
        git config --local user.email "action@github.com"
        git config --local user.name "GitHub Action"
        git add .
        git commit -m "Regenerated README"
        git push

One of these days, I’ll make an article about how all of these GitHub Actions files work. For now, however, this gives you an idea of how I automate everything.

Future Plans

This was a bit of a quick article as I promised myself that I wouldn’t do any more writing this summer. That said, I’ve been in the writing spirit, so I figured I’d create a short update on all the code I’ve been writing. Hopefully soon, the How To Python repo and series will be getting even more love!

Right now, I don’t have any plans for the docs generator, but I was thinking about pulling out some of the tools I’ve generated for general purpose use. For example, I have nice utilities for generating markdown. Those might be useful as a general purpose library.

Otherwise, that’s all I have! Hopefully, you liked this quick update. As always, if you’d like to support my work, check out this list of ways to grow the site. Take care!