Motllo

Repository templates just like I like them

• Quick visual example
• Motivation
• Description
• Example
• Usage
• Is it safe to use?
• Next steps

Quick visual example

Motivation

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. 

Description

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 tree UNIX 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).

Example

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!

Usage

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.

Is it safe to use?

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.

Next steps

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