Book: add links to commands

[presidento]

No description provided.

[sholderbach]

Thanks for this meticulous work! That really levels up the documentation!

[presidento]

It was just a simple Python script + cleaning up (reverting the non-related changes).

Although at its current state, it is hard to maintain. I suggest using a simple preprocessor step. In the source documentation use

`command:str camel-case`

and while building the documentation replace it wit

 `[str camel-case](/commands/docs/str_camel-case.md)`

I can write the script in Python, if you are willing to port it to Rust or whatever you like to use. (I do not know Rust.) Also, I can convert the existing documentation to use this format if it helps you.

[fdncred]

I wonder if this type of cleanup 1) is available via the CI, or 2) should be done in nushell vs any other language?

[presidento]

The preprocess step can be do, yes. I try to write it in Nushell if it is an available option. (You can run Nushell script in CI)

The cleaning step for the existing documentation is manual work. I added the link to every COMMAND with a script if the /commands/docs/COMMAND.md existed. Although there are cases when they seem to be commands, based on the context they are not. (For example shells file vs shells command, config environment variable vs config command.)

[presidento]

(Update: unfortunately Nushell does not support closure for str replace, just string replacement, so it would be tricky...)

[fdncred]

Let's run with this. Thanks!

[presidento]

FYI: as an exercise, I wrote a preprocessor PoC (fully functional, not production-grade quality).

def escape [] {(
    $in
    | str replace --all '🏀' '🏀0'
    | str replace --all '🥎' '🏀1'
    | str replace --all '⚽' '🏀2'
)}
def unescape [] {(
    $in
    | str replace --all '🏀2' '⚽'
    | str replace --all '🏀1' '🥎'
    | str replace --all '🏀0' '🏀'
)}
def handle-part [closure, part] {
    let type = ($part | str substring '0,1')
    let text = ($part | str substring '1,')
    if $type == '1' { do $closure ($text | split row '⚽' | unescape) | escape} else { $text }
}
def 'str replace-closure' [pattern, closure] {(
    '2' + $in
    | escape
    | str replace --all $pattern '🥎1$0⚽$1⚽$2⚽$3⚽$4⚽$5⚽$6⚽$7⚽$8⚽$9🥎2'
    | split row '🥎'
    | reduce --fold '' { |it, acc| $acc + (handle-part $closure $it) }
    | unescape
)}

##########################################################################

let add_link = { |match|
    let command = ($match.1 | str trim)
    let filename = ($command | str replace --all ' ' '_') + '.md'
    '[`' + $command + '`](/commands/docs/' + $filename + ')'
}

def preprocess_chapter [filepath] {
    let filename = ($filepath | path basename)
    echo $"Processing ($filename)"
    open $filepath | str replace-closure '`command:(.*?)`' $add_link | save -f $"book-COMPILED/($filename)"
}

rm -rf book-COMPILED
mkdir book-COMPILED
ls book/*.md | get name | each { |it| preprocess_chapter $it }