Repository templates just like I like them
It can be due to a bit of OCD and a bit of Knuth.
- Most "project template" systems (that let you create a repository with everything set up to use a library) need a specific repository for it (cookiecutter, giter8, GitHub's own template repositories). This feels weird to me, like needing a house to build a new house.
- I prefer more compact stuff I can read. Even better if I can document
So, here's motllo
[1284; del ll. mŏdŭlus 'mesura; mòdul', dimin. de modus 'mesura']
m 1 1 TECNOL METAL·L ART Peça amb una cavitat en la qual hom introdueix
una substància en forma de pols, de pasta o líquida per tal que, en
passar a l'estat sòlid, agafi la forma de la cavitat.
Motllo can convert a folder structure/repository (it more or less handles
.gitignore rules) into a Markdown document with:
- A "Tree structure" section
- Optionally, replacements to apply to the structure via the command line tool
- A tree representation of the folder structure you want (similar to the one
generated by the
treeUNIX utility, but in Python, thanks to a Stackoverflow answer by Aaron Hall) inside of a code block - Optionally, section links
- Sections, titled with the filepath described in the tree
- Optionally, replacement blocks for this filepath
- Code blocks (with possibly text describing what they are there for). All code blocks within a section are merged into that file
And, probably more importantly, given a document as above, it can convert it into a folder/repository structure, with variable replacement (in filenames as well as in code).
You can see an example of a basic Python CLI tool (like this one) as a template, with replacements and comments here.
You can convert that Markdown file into a folder structure with
motllo build PATH_TO/python_cli.md -o SOME_COOL_PATH -r "project_name:awesome-new-project" --commit
Without --commit you will only get an informational log about what operations will be performed
I plan on adding more examples at some point. New examples welcome!
The most easy uses are
motllo markdown . -o some_markdown.md
to generate the Markdown template from a repository, which will respect nested
and global .gitignore and then
motllo build markdown_template.md -o /wherever/ -r "project:cool-new-project" -r "version:0.0.1"
Here are the commands as shown in the CLI
Usage: motllo [OPTIONS] COMMAND [ARGS]...
Options:
--debug Set log level to debug
--help Show this message and exit.
Commands:
build Build a file/folder structure based on a Markdown document at...
markdown Generate a Markdown template from a folder or repository at PATH
tree Generate only the visual folder tree (like the UNIX tree...
Usage: motllo build [OPTIONS] PATH
Build a file/folder structure based on a Markdown document at PATH
Options:
-o, --output TEXT Destination path to create everything [required]
-r, --replace TEXT Multiple replacement rules separated by colons,
like -r "$PROJ:world_domination",
-r"$TOOLS:python"
--ignore-existing-folders Ignore if the destination folder already exists
--dry-run / --commit Dry run by default so you can see what it does
--help Show this message and exit.
Usage: motllo markdown [OPTIONS] PATH
Generate a Markdown template from a folder or repository at PATH. Will
ignore hidden files, you can use --force-include to add them
Options:
-x, --max-length INTEGER Maximum amount of lines to write in the
markdown, for each file. Use -1 for `all of
them`. Defaults to 15
-o, --output TEXT Destination markdown file [required]
--force-include TEXT Glob patterns to forcefully include, comma
separated between quotes like
"*.py,*.c,*.scala"
--ignore TEXT Glob patterns to ignore, comma separated
between quotes like "*.py,*.c,*.scala"
--gitignore / --no-gitignore Use local and global gitignores, yes by
default
--help Show this message and exit.
Usage: motllo tree [OPTIONS] PATH
Generate only the visual folder tree (like the UNIX tree command)
Options:
--force-include TEXT Glob patterns to forcefully include, comma
separated between quotes like
"*.py,*.c,*.scala"
--ignore TEXT Glob patterns to ignore, comma separated
between quotes like "*.py,*.c,*.scala"
--gitignore / --no-gitignore Use local and global gitignores, yes by
default
--help Show this message and exit.
Well, in dry run mode it will tell you what it will write, so pretty much yes. Don't blame me if it fails. Of course, I'd be happy to see it fail in the wild and improve it.
I want to refactor big chunks of the internals (I don't like parts of the API), and add some more testing, particularly around the replacements. This will be tricky, since generating random replacements is hard.
I will probably spin out the markdown parser (which was stolen from the one I wrote for bear-note-graph) into its own library