The Sample Programs repo just got even better with the addition of README automation. You’re not going to want to miss this one.
Table of Contents
What Is README Automation?
Back in 2018, I kicked off this collection of code snippets called Sample Programs. The idea was to collect as many code samples as possible in as many languages as possible.
Over time, we put a bunch of requirements in place, so code snippets were as consistent as possible. For example, we added documentation and testing for as many languages and programs as possible.
As the repo got larger, a lot of these tasks became unwieldy. For example, we started to ask a lot of contributors. If they added a new language, we would ask them to add testing. If they added a new program, we would ask them to provide documentation.
One of the very repetitive tasks was managing each language’s README. This was a pain because every program added would need to be documented and linked to an article issue.
Eventually, I realized that life would be easier if this process was automated, so I set out to write a script that would generate all of our READMEs any time new code was submitted to the repo.
Here’s what a README used to look like (with a permalink
, so you can see it rendered):
# Sample Programs in Python Welcome to Sample Programs in Python! To find documentation related to the Python code in this repo, look [here][trc-python-docs]. ## Sample Programs Below, you'll find a list of code snippets in this collection. Code snippets preceded by :warning: link to an article request issue while code snippets preceded by :white_check_mark: link to an existing article which provides further documentation. - :warning: [Baklava in Python][baklava-article-issue] - Solution borrowed from @erayak via the [baklava repo][baklava-repo] - :white_check_mark: [Binary Search][binary-search-article] - :white_check_mark: [Bubble Sort in Python][bubble-sort-article] - :warning: [Capitalize in Python][capitalize-article-issue] - :warning: [Convex Hull in Python][convex-hull-article-issue] - :white_check_mark: [Even Odd in Python][even-odd-article] - :white_check_mark: [Factorial in Python][factorial-article] - :white_check_mark: [Fibonacci in Python][fibonacci-article] - :white_check_mark: [File IO in Python][file-io-article] - :white_check_mark: [Fizz Buzz in Python][fizz-buzz-article] - :warning: [Game of Life in Python][game-of-life-article-issue] - :white_check_mark: [Hello World in Python][hello-world-article] - :white_check_mark: [Insertion Sort in Python][insertion-sort-article] - :warning: [Job Sequencing with Deadlines in Python][job-sequencing-article-issue] - :warning: [Longest Common Subsequence][lcs-article-issue] - :warning: [Longest Palindromic Subsequence][lps-article-issue] - :white_check_mark: [Merge Sort in Python][merge-sort-article] - :warning: [Minimum Spanning Tree][minimum-spanning-tree-article-issue] - :white_check_mark: [Prime Number in Python][prime-number-article] - :white_check_mark: [Quick Sort in Python][quick-sort-article] - :warning: [Quine in Python][quine-article-issue] - :white_check_mark: [Reverse a String in Python][reverse-a-string-article] - :white_check_mark: [Roman Numeral Conversion in Python][roman-numeral-article] - :warning: [ROT-13 in Python][rot-13-article-issue] - :white_check_mark: [Selection Sort in Python][selection-sort-article-issue] - :warning: [Sleep Sort in Python][sleep-sort-article-issue] ## Fun Facts - Debut: 1990 - Developer: Python Software Foundation - Typing: Dynamic - License: Python Software Foundation License - [Zen of Python][zen-of-python] ## References - [Python Wiki][python-wiki] - [Python Docs][python-website] - [Python REPL][python-online-repl] [baklava-repo]: https://github.com/toturkmen/baklava [python-online-repl]: https://repl.it/languages/python3 [python-website]: https://www.python.org/ [python-wiki]: https://en.wikipedia.org/wiki/Python_(programming_language) [zen-of-python]: https://www.python.org/dev/peps/pep-0020/ [binary-search-article]: https://sample-programs.therenegadecoder.com/projects/binary-search/python/ [bubble-sort-article]: https://sample-programs.therenegadecoder.com/projects/bubble-sort/python/ [even-odd-article]: https://sample-programs.therenegadecoder.com/projects/even-odd/python/ [factorial-article]: https://sample-programs.therenegadecoder.com/projects/factorial/python/ [fibonacci-article]: https://sample-programs.therenegadecoder.com/projects/fibonacci/python/ [file-io-article]: https://therenegadecoder.com/code/file-io-in-python/ [fizz-buzz-article]: https://therenegadecoder.com/code/fizz-buzz-in-python/ [hello-world-article]: https://therenegadecoder.com/code/hello-world-in-python/ [insertion-sort-article]: https://sample-programs.therenegadecoder.com/projects/insertion-sort/python/ [merge-sort-article]: https://sample-programs.therenegadecoder.com/projects/merge-sort/python/ [prime-number-article]: https://sample-programs.therenegadecoder.com/projects/prime-number/python/ [quick-sort-article]: https://sample-programs.therenegadecoder.com/projects/quick-sort/python/ [reverse-a-string-article]: https://therenegadecoder.com/code/reverse-a-string-in-python/ [roman-numeral-article]: https://sample-programs.therenegadecoder.com/projects/roman-numeral-conversion/python/ [trc-python-docs]: https://sample-programs.therenegadecoder.com/languages/python/ [baklava-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/190 [capitalize-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/390 [convex-hull-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/391 [game-of-life-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/237 [job-sequencing-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/70 [lcs-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/90 [lps-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/392 [minimum-spanning-tree-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/393 [quine-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/223 [rot-13-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/305 [selection-sort-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/110 [sleep-sort-article-issue]: https://github.com/TheRenegadeCoder/sample-programs-website/issues/394
Keep in mind that not all of the READMEs looked like this. This was one of the more maintained documents. Here’s what the automated file looks like (again, with a permalink):
# Sample Programs in Python
Welcome to Sample Programs in Python! To find documentation related to the Python
code in this repo, look [here](https://sample-programs.therenegadecoder.com/languages/python).
Otherwise, below you'll find a list of code snippets in this collection.
Code snippets preceded by :warning: link to a GitHub
issue query featuring a possible article request issue. If an article request issue
doesn't exist, we encourage you to create one. Meanwhile, code snippets preceded
by :white_check_mark: link to an existing article which provides further documentation.
- :warning: [Baklava in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+baklava+python)
- :white_check_mark: [Binary Search in Python](https://sample-programs.therenegadecoder.com/projects/binary-search/python)
- :white_check_mark: [Bubble Sort in Python](https://sample-programs.therenegadecoder.com/projects/bubble-sort/python)
- :warning: [Capitalize in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+capitalize+python)
- :warning: [Convex Hull in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+convex+hull+python)
- :white_check_mark: [Even Odd in Python](https://sample-programs.therenegadecoder.com/projects/even-odd/python)
- :white_check_mark: [Factorial in Python](https://sample-programs.therenegadecoder.com/projects/factorial/python)
- :white_check_mark: [Fibonacci in Python](https://sample-programs.therenegadecoder.com/projects/fibonacci/python)
- :white_check_mark: [File Io in Python](https://sample-programs.therenegadecoder.com/projects/file-io/python)
- :white_check_mark: [Fizz Buzz in Python](https://sample-programs.therenegadecoder.com/projects/fizz-buzz/python)
- :warning: [Fraction in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+fraction+python)
- :warning: [Game Of Life in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+game+of+life+python)
- :white_check_mark: [Hello World in Python](https://sample-programs.therenegadecoder.com/projects/hello-world/python)
- :white_check_mark: [Insertion Sort in Python](https://sample-programs.therenegadecoder.com/projects/insertion-sort/python)
- :warning: [Job Sequencing in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+job+sequencing+python)
- :warning: [Lcs in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+lcs+python)
- :white_check_mark: [Linear Search in Python](https://sample-programs.therenegadecoder.com/projects/linear-search/python)
- :warning: [Lps in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+lps+python)
- :white_check_mark: [Maximum Subarray in Python](https://sample-programs.therenegadecoder.com/projects/maximum-subarray/python)
- :white_check_mark: [Merge Sort in Python](https://sample-programs.therenegadecoder.com/projects/merge-sort/python)
- :warning: [Minimum Spanning Tree in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+minimum+spanning+tree+python)
- :white_check_mark: [Prime Number in Python](https://sample-programs.therenegadecoder.com/projects/prime-number/python)
- :white_check_mark: [Quick Sort in Python](https://sample-programs.therenegadecoder.com/projects/quick-sort/python)
- :warning: [Quine in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+quine+python)
- :warning: [Reverse String in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+reverse+string+python)
- :warning: [Roman Numeral in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+roman+numeral+python)
- :warning: [Rot 13 in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+rot+13+python)
- :white_check_mark: [Selection Sort in Python](https://sample-programs.therenegadecoder.com/projects/selection-sort/python)
- :warning: [Sleep Sort in Python](https://github.com//TheRenegadeCoder/sample-programs-website/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+sleep+sort+python)
Overall, it’s quite slimmed down. Two sections were removed. That said, all of the links are automatically generated, so we can see which programs are documented and which are not.
All that said, this probably doesn’t seem that exciting. Don’t worry! There are two more updates to come shortly.
Why Add README Automation?
As mentioned above, part of the rationale was user experience. It’s much nicer for a new contributor if they can just plug a hole (i.e., provide code) while some automated tool handles updating everything else.
It’s also very nice for the maintainers because we no longer have to beg contributors to update the documents for us. Likewise, streamlines our contributing doc as a consequence which means folks are more likely to read it. That’s a double win!
I personally like the README automation because it means I can change the READMEs pretty much whenever I want and the changes will propagate to all the READMEs. In fact, this article details 2.0.0, but at the time of writing, 2.2.0 is out. In other words, I have iterated on the READMEs a handful of times now and propagated the changes.
Beyond that, I think another huge benefit of this is consistent README styling across the repo. Prior to the development of this tool, the READMEs were like the wild west. Sure, we had a template, but there was no way to ensure they we consistent.
To be honest, I could keep selling this feature, but you probably only have so much time in your day. So, we’ll move on!
How Does README Automation Work?
In short, README automation works in two phases. First, we use the same infrastructure that we use to generate wiki pages to generate README pages. In other words, we scan the repo and build up some objects representing what we’ve learned. In the second phase, we take those objects and generate README pages from them.
For the automation to actually occur, however, we need to build it into our continuous integration. For this, we’re using GitHub actions as follows:
- name: Generate READMEs
run: |
pip install generate_docs==2.0.3
wikir archive/
- name: Commit READMEs
uses: EndBug/add-and-commit@v5
with:
message: |
Generated READMEs from sources [skip ci]
on-behalf-of: @TheRenegadeCoder <jeremy.grifski@therenegadecoder.com>
author_name: Jeremy Grifski
author_email: jeremy.grifski@therenegadecoder.com
env:
# This is necessary in order to push a commit to the repo
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # Leave this line unchanged
This YAML file then installs our script and runs it on our archive. When it’s done, we take the generated READMEs, and we commit them to our repo.
If you’re interested in the nitty gritty details of how the READMEs are generated in the first place, I’d check out the repo itself, so you can see the code.
Other Changes?
One thing you might be surprised by is the version number. “Wait a second,” you might be saying, “I’ve never heard of the Sample Programs Docs Generator. How is it on version 2?”
This is a wonderful question and alludes to one of the bigger changes that I neglected to mention up to this point. Prior to being called the Sample Programs Docs Generator, this repo was called the Sample Programs Wiki Generator, and I used it to automate the Sample Programs Wiki.
By renaming the repo from wiki to docs, we can encompass significantly more documentation related improvements. Also, we can reuse a lot of the code, which I think is very important.
Beyond that, however, this is the first version of the new tool, so not much has changed. The only thing worth mentioning is that a lot of code was refactored and moved around. Specifically, this went from a single script to about five modules. That said, I think the restructuring was for the best!
Plans for the Future?
As mentioned several times in this post, at the time of writing, Docs Generator actually features a couple more minor updates, which we’ll feature on this site shortly. For example, we added testing to every README, so users can see what we’re using to test the language as well as how to test the language if it isn’t currently tested. Likewise, we added a feature that blocks builds if a program doesn’t have requirements.
Beyond that, there’s not much else to say. If you have any ideas for this tool, let me know! I’m happy to keep working on it. Otherwise, take care!
Recent Meta Posts
Rarely do I like to fill up this site with ramblings about my life, but this year has been off the rails. As a result, I can't seem to inspire myself to write about software. Instead, I'd like to...
Life has given me a bit of a beating, so I'm taking some time to recover. See y'all again soon.