CLI Help

When using compose.mk directly, help not only works, it goes beyond simply listing available targets, and actually parses and displays documentation per target, and per target-namespace. Python-style docstrings are supported for targets, and markdown in those docstrings is supported and rendered. Here are some ways to ask for help:

# List all targets 
$ ./compose.mk help

# Pretty-print help for a single target 
$ ./compose.mk help/docker.run

# Works for multiple targets, using prefix search
$ ./compose.mk help/docker

# Adding arguments directly with no slash also works if using `compose.mk` directly,
# but project Makefiles cannot inherit this by including compose.mk as a library
./compose.mk help docker

Under the hood, help uses a dockerized version of mk.parse and charmbracelete/glow. Because this uses containers, be advised that rendering help can be slow, especially the first time it runs. See the implementation details section for more about this, and other hints for granular access to the moving pieces involved here.

Help For Project Makefiles

To enable help your project Makefile, there are a few options depending on how tightly you want to integrate, but usually it's enough to just include compose.mk somewhere near the top of your file.

# List only targets that are static and local, i.e.
# targets which are not scaffolded, and are not included from other Makefiles
$ make help.local

# Pretty-print help for a single target or prefix
$ make help.local/build

# Print all help for all local targets
$ make help.local.all

Docstring Style

Note that for help to render properly, your targets need to use the following style for comments, similar to python-style docstrings. (There is no support for other kinds of comments that are above or inside of target-bodies.)

Summary 
#!/usr/bin/env -S make -f
# demos/cli-help.mk: 
#   Demonstrates CLI-help and supported syntax for docstrings.
#   Part of the `compose.mk` repo. This file runs as part of the test-suite.  
#
# USAGE:  ./demos/cli-help.mk

include compose.mk 

__main__: my-target my-parametric-target/FOO

my-target:
    @# Comment line one
    @# **Markdown is supported.**
    echo your implementation here

my-parametric-target/%:
    @# Comment line one
    @# **Markdown is supported.**
    echo your implementation here

Implementation Details

Since help involves targets and target-metadata, it's also a special case of reflection, which you can read more about in the standard-library docs.

Heavy lifting for parsing metadata comes from a dockerized version of the mk.parse tool1 which extracts and displays docstrings, as well as other details like target-prerequisites.

To see example output or just precache the mk.parse container, you can use mk.parse/<some_makefile>. To get an idea about the schema, we can use compose.mk to parse it's own content, then show the JSON structure for the mk.parse target itself.

$ ./compose.mk mk.parse/compose.mk

{
  ..
  "mk.parse/%": {
    "file": "compose.mk",
    "lineno": 2323,
    "parametric": true,
    "docs": [
      " Parses the given Makefile, returning JSON output that describes the targets, docs, etc.",
      " This parsing is \"deep\", i.e. it returns docs & metadata for *included* targets as well.",
      " This uses a dockerized version of the mkparse[1] tool.",
      "",
      " REFS:",
      "   * `[1]`: https://github.com/mattvonrocketstein/mk.parse/"
    ],
    "prereqs": [],
    "local": true,
    "private": false,
    "regex": "mk.parse/.*",
    "implementors": []
  },
  ..

References

  1. mk.parse tool ↩