Autogenerated Documentation For Justfiles

autodoc-justfile.py

#!/usr/bin/env python3
# Autogenerated Documentation For Justfiles
# This was created to support this issue ticket https://github.com/casey/just/issues/2033#issuecomment-2278336973
import json
import subprocess
from typing import Any

# just --dump --dump-format json --unstable | jq > test.json
json_output = subprocess.run(
    ["just", "--dump", "--dump-format", "json", "--unstable"],
    check=True,
    capture_output=True,
).stdout

def markdown_table_with_alignment_support(header_map: list[dict[str, str]], data: list[dict[str, Any]]):
    # JSON to Markdown table formatting: https://stackoverflow.com/a/72983854/2850957

    # Alignment Utility Function
    def strAlign(padding: int, alignMode: str | None, strVal: str):
        if alignMode == 'center':
            return strVal.center(padding)
        elif alignMode == 'right':
            return strVal.rjust(padding - 1) + ' '
        elif alignMode == 'left':
            return ' ' + strVal.ljust(padding - 1)
        else: # default left
            return ' ' + strVal.ljust(padding - 1)

    def dashAlign(padding: int, alignMode: str | None):
        if alignMode == 'center':
            return ':' + '-' * (padding - 2) + ':'
        elif alignMode == 'right':
            return '-' * (padding - 1) + ':'
        elif alignMode == 'left':
            return ':' + '-' * (padding - 1)
        else: # default left
            return '-' * (padding)

    # Calculate Padding For Each Column Based On Header and Data Length
    rowsPadding = {}
    for index, columnEntry in enumerate(header_map):
        padCount = max([len(str(v)) for d in data for k, v in d.items() if k == columnEntry['key_name']], default=0) + 2
        headerPadCount = len(columnEntry['header_name']) + 2
        rowsPadding[index] = headerPadCount if padCount <= headerPadCount else padCount

    # Render Markdown Header
    rows = []
    rows.append('|'.join(strAlign(rowsPadding[index], columnEntry.get('align'), str(columnEntry['header_name'])) for index, columnEntry in enumerate(header_map)))
    rows.append('|'.join(dashAlign(rowsPadding[index], columnEntry.get('align')) for index, columnEntry in enumerate(header_map)))

    # Render Tabular Data
    for item in data:
        rows.append('|'.join(strAlign(rowsPadding[index], columnEntry.get('align'), str(item[columnEntry['key_name']])) for index, columnEntry in enumerate(header_map)))

    # Convert Tabular String Rows Into String
    tableString = ""
    for row in rows:
        tableString += f'|{row}|\n'

    return tableString

def recipe_one_line_short(stuff):
    command_args = stuff["name"]

    if len(stuff["parameters"]) > 0:
        for parameter_entry in stuff["parameters"]:
            parameter_name = parameter_entry["name"].upper()
            if parameter_entry["kind"] == "singular":
                if parameter_entry["default"] is not None:
                    # Singular Argument. Default value used if missing
                    command_args += f" {{{parameter_name}}}"
                else:
                    # Singular Argument. Must provide value
                    command_args += f" <{parameter_name}>"
            elif parameter_entry["kind"] == "plus":
                # One or more arguments
                command_args += f" [{parameter_name}... 1 or more]"
            elif parameter_entry["kind"] == "star":
                # Zero or more arguments (optional option)
                command_args += f" [{parameter_name}... 0 or more]"

    return command_args


def captialise_sentences(text: str):
    lines = text.split('. ')
    for index, line in enumerate(lines):
        if len(line) > 1:
            lines[index] = line[0].upper() + line[1:]
    return '. '.join(lines)


data = json.loads(json_output)
recipes = data["recipes"]

print("# Justfile Autogenerated Documentation")
print("")

print("## Recipe List")
print("- Legend")
print("  - `{ARG}` : Singular Argument. Default Value Avaliable If Missing")
print("  - `<ARG>` : Singular Argument. Must Provide Value")
print("  - `[ARG... 1 or more]` : Varidict Argument. Must Provide At Least One Value")
print("  - `[ARG... 0 or more]` : Varidict Argument. Optionally Provide Multiple Values")

# Main Recipes
print("")
print("### Main Recipe")
recipe_list_table: list[dict[str, str | int]] = []

for recipe_name, stuff in recipes.items():
    if recipe_name[0] == "_":
        continue
    recipe_list_table.append({"recipe_name":f"[`{recipe_one_line_short(stuff)}`](#{recipe_name})", "doc":captialise_sentences(stuff.get('doc') or "")})

recipe_list_header_map = [
    {'key_name':'recipe_name',      'header_name':'Recipe',      'align':'left'},
    {'key_name':'doc',              'header_name':'Description', 'align':'left'}
]
print(markdown_table_with_alignment_support(recipe_list_header_map, recipe_list_table))

# Internal Recipes
print("")
print("### Internal Recipe")
recipe_list_table: list[dict[str, str | int]] = []

for recipe_name, stuff in recipes.items():
    if recipe_name[0] != "_":
        continue
    recipe_list_table.append({"recipe_name":f"[`{recipe_one_line_short(stuff)}`](#{recipe_name})", "doc":stuff.get('doc') or ""})

recipe_list_header_map = [
    {'key_name':'recipe_name',      'header_name':'Recipe',      'align':'left'},
    {'key_name':'doc',              'header_name':'Description', 'align':'left'}
]

print(markdown_table_with_alignment_support(recipe_list_header_map, recipe_list_table))

print("")
print("---")
print("")
print("## Recipe Details")

for recipe_name, stuff in recipes.items():
    print("")
    print(f"## <a id=\"{recipe_name}\"> {recipe_name} </a>")
    print(f"- Command: `{recipe_one_line_short(stuff)}`")
    if len(stuff["parameters"]) > 0:
        print(f"- Arguments:")
        for parameter_entry in stuff["parameters"]:
            print(f'  - `{parameter_entry["name"].upper()}`')

            if parameter_entry["kind"] == "plus":
                print(f'    - One or more arguments')
            elif parameter_entry["kind"] == "star":
                print(f'    - Zero or more arguments')

            if parameter_entry["default"] is not None:
                if isinstance(parameter_entry["default"], str):
                    print(f'    - Default Value: {parameter_entry["default"]}')
                elif isinstance(parameter_entry["default"], list):
                    if parameter_entry["default"][0] == "evaluate":
                        print(f'    - Default Value: evaluate(`{parameter_entry["default"][1]}`)')
                    else:
                        print(f'    - Default Value: ??(`{parameter_entry["default"][1]}`)')
                else:
                    print(f'    - Default Value: `{parameter_entry["default"]}`)')

    if len(stuff["dependencies"]) > 0:
        print("- Dependencies:")
        for dependent_recipe_name in [d["recipe"] for d in recipes.get(recipe_name)["dependencies"]]:
            print(f'  - [{dependent_recipe_name}](#{dependent_recipe_name})')

    # Print description
    if stuff["doc"] is not None:
        print("")
        print(captialise_sentences(stuff.get("doc", "")))
    elif (stuff["body"] is None or len(stuff["body"]) <= 0) and (len(stuff["dependencies"]) > 0):
        # No code but has dependencies, likely a meta command
        print("")
        print(f"Run all {recipe_name} recipies")

    if stuff["body"] is not None and len(stuff["body"]) > 0:
        print("")
        print("```bash")
        for body_line in stuff["body"]:
            line = ""
            for piece in body_line:
                if isinstance(piece, str):
                    line += piece
                elif piece[0][0] == "variable":
                    line += f"{{{{{piece[0][1]}}}}}"
                elif piece[0][0] == "call":
                    line += f"{{{{{piece[0][1]}()}}}}"
                else:
                    line += f"{piece}"
            print(line)
        print("```")

    if len(stuff["dependencies"]) > 0:
        print("")
        print("```mermaid")
        print("graph LR")

        def call_graph_gen(recipe_name):
            if recipe_name not in recipes:
                return
            stuff = recipes.get(recipe_name)
            dependencies = [d["recipe"] for d in stuff["dependencies"]]
            for d in dependencies:
                print(f'    {recipe_name} --> {d}')
                print(f'    click {d} "#{d}"')
                call_graph_gen(d)

        call_graph_gen(recipe_name)
        print("```")

This is how the above will generate the below document from just's justfile itself:

Justfile Autogenerated Documentation

Recipe List

• Legend
  • {ARG} : Singular Argument. Default Value Avaliable If Missing
  • <ARG> : Singular Argument. Must Provide Value
  • [ARG... 1 or more] : Varidict Argument. Must Provide At Least One Value
  • [ARG... 0 or more] : Varidict Argument. Optionally Provide Multiple Values

Main Recipe

Recipe	Description
build
build-book
check
ci
clippy	Everyone's favorite animate paper clip
convert-integration-test <TEST>
done {BRANCH}	Clean up feature branch BRANCH
filter <PATTERN>	Only run tests matching PATTERN
fmt
forbid
fuzz
generate-completions
install	Install just from crates.io
install-dev-deps	Install development dependencies
man
polyglot	Run all polyglot recipes
pr
publish	Publish current GitHub master branch
push
pwd	Print working directory, for demonstration purposes!
quine	Make a quine, compile it, and verify it
readme-version-notes
render-readme
replace <FROM> <TO>
run
shellcheck
sloc	Count non-empty lines of code
test
test-completions
test-quine
update-changelog	Add git log messages to changelog
update-contributors
view-man
watch [ARGS... 1 or more]
watch-readme

Internal Recipe

Recipe	Description
_js
_nu
_perl
_python
_ruby
_sh

---

Recipe Details

_js

• Command: _js

#!/usr/bin/env node
console.log('Greetings from JavaScript!')

_nu

• Command: _nu

#!/usr/bin/env nu
let hellos = ["Greetings", "Yo", "Howdy"]
$hellos | each {|el| print $"($el) from a nushell script!" }

_perl

• Command: _perl

#!/usr/bin/env perl
print "Larry Wall says Hi!\n";

_python

• Command: _python

#!/usr/bin/env python3
print('Hello from python!')

_ruby

• Command: _ruby

#!/usr/bin/env ruby
puts "Hello from ruby!"

_sh

• Command: _sh

#!/usr/bin/env sh
hello='Yo'
echo "$hello from a shell script!"

build

• Command: build

cargo build

build-book

• Command: build-book

cargo run --package generate-book
mdbook build book/en
mdbook build book/zh

check

• Command: check
• Dependencies:
  • fmt
  • clippy
  • test
  • forbid

#!/usr/bin/env bash
set -euxo pipefail
git diff --no-ext-diff --quiet --exit-code
VERSION=`sed -En 's/version[[:space:]]*=[[:space:]]*"([^"]+)"/\1/p' Cargo.toml | head -1`
grep "^\[$VERSION\]" CHANGELOG.md

graph LR
    check --> fmt
    click fmt "#fmt"
    check --> clippy
    click clippy "#clippy"
    check --> test
    click test "#test"
    check --> forbid
    click forbid "#forbid"

Loading

ci

• Command: ci
• Dependencies:
  • build-book

cargo test --all
cargo clippy --all --all-targets -- --deny warnings
cargo fmt --all -- --check
./bin/forbid
cargo update --locked --package just

graph LR
    ci --> build-book
    click build-book "#build-book"

Loading

clippy

• Command: clippy

Everyone's favorite animate paper clip

cargo clippy --all --all-targets --all-features

convert-integration-test

• Command: convert-integration-test <TEST>
• Arguments:
  • TEST

cargo expand --test integration {{test}} | \
  sed \
  -E \
  -e 's/#\[cfg\(test\)\]/#\[test\]/' \
  -e 's/^ *let test = //' \
  -e 's/^ *test[.]/./' \
  -e 's/;$//' \
  -e 's/crate::test::Test/Test/' \
  -e 's/\.run\(\)/.run();/'

done

• Command: done {BRANCH}
• Arguments:
  • BRANCH
    • Default Value: evaluate(git rev-parse --abbrev-ref HEAD)

Clean up feature branch BRANCH

git checkout master
git diff --no-ext-diff --quiet --exit-code
git pull --rebase github master
git diff --no-ext-diff --quiet --exit-code {{BRANCH}}
git branch -D {{BRANCH}}

filter

• Command: filter <PATTERN>
• Arguments:
  • PATTERN

Only run tests matching PATTERN

cargo test {{PATTERN}}

fmt

• Command: fmt

cargo fmt --all

forbid

• Command: forbid

./bin/forbid

fuzz

• Command: fuzz

cargo +nightly fuzz run fuzz-compiler

generate-completions

• Command: generate-completions

./bin/generate-completions

install

• Command: install

Install just from crates.io

cargo install -f just

install-dev-deps

• Command: install-dev-deps

Install development dependencies

rustup install nightly
rustup update nightly
cargo +nightly install cargo-fuzz
cargo install cargo-check
cargo install cargo-watch
cargo install mdbook mdbook-linkcheck

man

• Command: man

cargo run -- --man > man/just.1

polyglot

• Command: polyglot
• Dependencies:
  • _python
  • _js
  • _perl
  • _sh
  • _ruby

Run all polyglot recipes

graph LR
    polyglot --> _python
    click _python "#_python"
    polyglot --> _js
    click _js "#_js"
    polyglot --> _perl
    click _perl "#_perl"
    polyglot --> _sh
    click _sh "#_sh"
    polyglot --> _ruby
    click _ruby "#_ruby"

Loading

pr

• Command: pr
• Dependencies:
  • push

gh pr create --web

graph LR
    pr --> push
    click push "#push"
    push --> check
    click check "#check"
    check --> fmt
    click fmt "#fmt"
    check --> clippy
    click clippy "#clippy"
    check --> test
    click test "#test"
    check --> forbid
    click forbid "#forbid"

Loading

publish

• Command: publish

Publish current GitHub master branch

#!/usr/bin/env bash
set -euxo pipefail
rm -rf tmp/release
git clone [email protected]:casey/just.git tmp/release
cd tmp/release
! grep '<sup>master</sup>' README.md
VERSION=`sed -En 's/version[[:space:]]*=[[:space:]]*"([^"]+)"/\1/p' Cargo.toml | head -1`
git tag -a $VERSION -m "Release $VERSION"
git push origin $VERSION
cargo publish
cd ../..
rm -rf tmp/release

push

• Command: push
• Dependencies:
  • check

! git branch | grep '* master'
git push github

graph LR
    push --> check
    click check "#check"
    check --> fmt
    click fmt "#fmt"
    check --> clippy
    click clippy "#clippy"
    check --> test
    click test "#test"
    check --> forbid
    click forbid "#forbid"

Loading

pwd

• Command: pwd

Print working directory, for demonstration purposes!

echo {{invocation_directory()}}

quine

• Command: quine

Make a quine, compile it, and verify it

mkdir -p tmp
@echo '{{quine-text}}' > tmp/gen0.c
cc tmp/gen0.c -o tmp/gen0
./tmp/gen0 > tmp/gen1.c
cc tmp/gen1.c -o tmp/gen1
./tmp/gen1 > tmp/gen2.c
diff tmp/gen1.c tmp/gen2.c
rm -r tmp
@echo 'It was a quine!'

readme-version-notes

• Command: readme-version-notes

grep '<sup>master</sup>' README.md

render-readme

• Command: render-readme

#!/usr/bin/env ruby
require 'github/markup'
$rendered = GitHub::Markup.render("README.adoc", File.read("README.adoc"))
File.write('tmp/README.html', $rendered)

replace

• Command: replace <FROM> <TO>
• Arguments:
  • FROM
  • TO

sd '{{FROM}}' '{{TO}}' src/*.rs

run

• Command: run

cargo run

shellcheck

• Command: shellcheck

shellcheck www/install.sh

sloc

• Command: sloc

Count non-empty lines of code

@cat src/*.rs | sed '/^\s*$/d' | wc -l

test

• Command: test

cargo test

test-completions

• Command: test-completions

./tests/completions/just.bash

test-quine

• Command: test-quine

cargo run -- quine

update-changelog

• Command: update-changelog

Add git log messages to changelog

echo >> CHANGELOG.md
git log --pretty='format:- %s' >> CHANGELOG.md

update-contributors

• Command: update-contributors

cargo run --release --package update-contributors

view-man

• Command: view-man
• Dependencies:
  • man

man man/just.1

graph LR
    view-man --> man
    click man "#man"

Loading

watch

• Command: watch [ARGS... 1 or more]
• Arguments:
  • ARGS
    • One or more arguments
    • Default Value: test

cargo watch --clear --exec '{{args}}'

watch-readme

• Command: watch-readme

just render-readme
fswatch -ro README.adoc | xargs -n1 -I{} just render-readme

This is nice. After trying, it appears this currently does not recognise modules or groups, am I correct?

A workaround can be to build documentation for each module individually.

Well it's a proof of concept, so not expecting this to cover everything. But yeah, all these are good ideas. But that would require bit more standardization of the justfile json output I think.

If you want more progress, best to throw your effort at this ticket casey/just#2033 (comment) @almereyda