1 - Description
2 - Installation
2.1 - Prerequisites
2.2 - Instructions
2.3 - Dependancies
3 - Usage
3.1 - Interactive mode
3.2 - Templating
3.3 - Best practices
4 - Tests
5 - Roadmap
6 - Contributing
7 - License
This Python tool has been designed to generate (flavoured) markdown files for GitHub repositories. It includes basic badges and RepoBeats generation options as well as multiple basic integrated methods to render markdown elements inside recursive section objects.
It can be useful to kickstart personal projects as it includes templating options via Mardown & Section objects methods calls.
Moreover, a wide range of flavoured markdown (GitHub Markdown) features are supported by the templated-compatible interactive mode commands.
Note that some commands only generate a "base of content". Thus, generated content (example: custom-size table) may have to be updated after interactive mode.
The package was written on Python 3.12 version but supported versions will be determined when the package will be released on PyPi.
This section will be updated accordingly with the first PyPi realease.
To work with the tool on your machine and start templating with your own preferences, you can clone the repo or download the PyPi package using pip ...
Cloning the repository ...
git clone https://github.com/Lpwlk/ReadmeEngine.git
Downloading the PyPi package ...
pip install readme-engine
The engine is built on top of the rich package for CLI rendering in interactive mode as well as for verbose features & tools provided by both python objects.
The tool is designed using a tree structure for sections and section's contents. Every element (Section or content) can me moved/edited or removed using commands and help utilities are available withing every interactive menu & submenus.
The interactive mode can be started using the run method on Markdown object instance. It includes several submenus for header/footer generation as well as section structure & content management.
import readme-engine
md = Markdown()
md.run()
Every menu & submenu includes a help utility which describes every available commands.
Templating consists of Markdown & Section objects recursive calls within a script to create various kinds of README.md structures with control on titles and contents.
Some methods still need to be updated to be fully available externally (some work only in interactive mode as they are not supposed to be very useful when it comes to template creation from outside the source-code).
However, some structure display methods such as tree_sections and list_sections are available for the typical usecase described in the next subsection (Best practices). Future commits will include some example scripts using all available methods for personal templating purposes.
The ideal use of this tool would be to design your own base template for some of your (future) projects and to call interactive mode on the templated object in order to automate your README.md redactions/updates (fast copy&paste of previous markdown content works well with interactive mode prompts).
import readme-engine
md = Markdown()
md.add_section(Section(title = 'Description', content = ['Project description.']))
md.add_section(Section(title = 'Installation'))
usage = Section('Usage')
usage.add_section(Section('Best practices'))
md.add_section(usage)
md.run() # Calling interactive mode on Markdown object to edit previous template
This methodology can be reproduced inside the 'temp' command in main interactive run menu with the default Markdown template. This command reinitialize the whole Markdown structure & content to create the selected default template.
The /tests directory includes rich-generated .svg files of terminal output of the script in pure templating as well as pure interactive contexts with the corresponding generated markdown file.
Future commits should include unit-tests for every methods references as available for templating in the Usage section.
- Update .gitignore & clean repo before next commit
- Implementation of one-line prompts for section selects [canceled because not efficient]
- Implement details tag option for foldable content creation in content creation mode
- Full command coverage test w/ .svg output generation for CLI rendering validation alongside
- Add block-comments under major methods of both Markdown & Section objects
- Define clear styles names for each contexts & specific elements
- Include/update styles in every console outputs
- Define external methods availability for external templating use & update accordingly
- Reference every available methods for the end-user w/ descrition in Usage > Templating
- Write unit tests for every methods externally available in /tests
Pull requests are welcome. For major changes, please fell free to open an issue first to discuss what you would like to change and in which way you would like to to it.
The project is currently published under MIT license which allows very flexible use for any kind of purposes and contributions.
