Keep your code snippets in README up-to-date!
Posted by Better-Banana4069@reddit | Python | View on Reddit | 13 comments
Code-Embedder
Links: GitHub, GitHub Actions Marketplace
What My Project Does
Code Embedder is a GitHub Action that automatically updates code snippets in your markdown (README) files. It finds code blocks in your README that reference specific scripts, then replaces these blocks with the current content of those scripts. This keeps your documentation in sync with your code.
✨ Key features
- 🔄 Automatic synchronization: Keep your
READMEcode examples up-to-date without manual intervention. - 🛠️ Easy setup: Simply add the action to your GitHub workflow and format your
READMEcode blocks. - 📝 Section support: Update only specific sections of the script in the
README. - 🧩 Object support: Update only specific objects (functions, classes) in the
README. The latest version v0.5.1 supports only 🐍 Python objects (other languages to be added soon).
Find more information in GitHub 🎉
Target Audience
It is a production-ready, tested Github Action that can be part of you CICD workflow to keep your READMEs up-to-date.
Comparison
It is a light-weight package with primary purpose to keep your code examples in READMEs up-to-date. MkDocs is a full solution to creating documentation as a code, which also offers embedding external files. Code-Embedder is a light-weight package that can be used for projects with or without MkDocs. It offers additional functionality to sync not only full scripts, but also a section of a script or a 🐍 Python function / class definition.
gagarin_kid@reddit
The documentation in the README is amazingly written! Also waiting for a pre-commit functionality which changes the Readme file locally
Better-Banana4069@reddit (OP)
thank you
batero84@reddit
Pretty nice! I'm saving this post for later, when an integration with a pre-commit hook exists. Great job!
Better-Banana4069@reddit (OP)
Thank you!:)
Significant-Gur-7656@reddit
Thank you!:) great, working on it:))
guyfrom7up@reddit
I love the idea of it, but I would like to use it as a pre-commit hook instead of a github action. Any desire of adding that functionality?
Better-Banana4069@reddit (OP)
That's a great idea, yes I will add that functionality too:) Putting it to my high prio list, it will be part of my next release
1473-bytes@reddit
Looks nice! I've been meaning to move my code blocks in README into files to be able to unit test the documentation. This looks great for a lightweight way to keep docs in-sync!
Better-Banana4069@reddit (OP)
Thanks!:) yep, I've seen many repositories with out-of-date code and for a new user it was perplexing. Combining the code-embedder with unit testing functionality to make sure the examples are up to date sounds great.
I've been also thinking about how to also make sure that the examples are runnable but this is a harder task to generalize across different languages. It would nevertheless be a nice future feature of the code-embedder:)
Aveheuzed@reddit
Nice tool! What languages do you support ? Only Python for object references, but for sections embeds?
Better-Banana4069@reddit (OP)
Section support is for all languages, objects are for Python only as of now, other languages will be added in next releases:))
shrekofspeed@reddit
Just tried it on my repo. Good job on making it easy to use!
Better-Banana4069@reddit (OP)
That's great!