Add Help page with generated markdown output for all commands and topics

Author: mgrojo

_config.yml

@@ -46,6 +46,7 @@ header_pages:
   - crates.md
   - search.html
   - docs/index.md
+  - docs/index-alr.md
 
 # Devlopr
 author_logo: profile.png

alr-help-md.sh

@@ -0,0 +1,63 @@
+#!/bin/bash
+
+# Safer shell
+set -o nounset
+set -o errexit
+
+alr_version=$(alr --no-tty version | grep "alr version" | cut -d: -f2 | tr -d '[:blank:]')
+alire_lib_version=$(alr --no-tty version | grep "libalire version" | cut -d: -f2 | tr -d '[:blank:]')
+
+# Print a horizontal rule and Alire versions
+function print_version () {
+    echo
+    echo "---------------------------------------------------------"
+    echo "Alr \`${alr_version}\`."
+    echo "Alire Library \`${alire_lib_version}\`."
+    echo
+}
+
+# $1 : page title
+function print_header () {
+    echo "---"
+    echo "title: $1"
+    echo "layout: page"
+    echo "---"
+}
+
+topic_list=$(alr help | awk '/^ +[a-z]+/ {if ($1 !~ "alr") {print $1}}')
+
+mkdir -p man
+
+# Make a page from each help topic
+for topic in $topic_list; do
+    if alr --markdown help $topic > /dev/null 2>&1 ; then
+        echo "Info: generating alr-${topic}.md"
+        {
+            print_header "alr $topic"
+            alr --markdown help $topic
+            print_version
+        } > alr-${topic}.md
+    else
+        echo "Warning: skipping \"${topic}\"; it might be an invalid topic" >&2
+    fi
+done
+
+# Make an index from the help subcommand.
+{
+    print_header "alr help"
+    # For every line starting by possible whitespace and a code word (topic),
+    #   if the word matches an existing alire help page then
+    #     replace word by a link to the page.
+    # For any other line, print as is.
+    alr --markdown help | awk '
+/^ +`[a-z]+`/ {
+    topic=gensub(/`/, "", "g", $1)
+    if (system("test -f alr-" topic ".md") == 0) {
+       sub(/`[a-z]+`/, "[`" topic "`](alr-" topic ")")
+   }
+}
+{
+    print
+}'
+    print_version
+} > alr-help.md

docs/index-alr.md

@@ -0,0 +1,73 @@
+---
+title: Help
+description: "alr manual pages"
+layout: default
+---
+<div class="card">
+  <style>
+/* Create two equal columns that floats next to each other */
+.doc_toc {
+  float: left;
+  width: 15em;
+}
+
+.doc_content {
+  float: left;
+  width: calc(100% - 15em);
+}
+
+/* Clear floats after the columns */
+.doc_row:after {
+  content: "";
+  display: table;
+  clear: both;
+}
+
+/* Responsive layout - makes the two columns stack on top of each other instead
+of next to each other */
+
+@media screen and (max-width: 60em) {
+  .doc_toc {
+    width: 100%;
+  }
+  .doc_content {
+    width: 100%;
+  }
+}
+
+/* Table-of-content style */
+#markdown-toc {
+  padding-left: 1em;
+  font-size: smaller;
+}
+#markdown-toc ul {
+  padding-left: 1em;
+}
+
+
+</style>
+<div class="doc_row">
+ <div class="doc_toc">
+  <div markdown="1">
+
+   * Do not remove this line (it will not be displayed)
+   {:toc}
+
+  </div>
+  <small style="color:#808080">
+      This help documentation has been generated from the builtin `alr` help
+      messages. Don't hesitate to suggest fix(es) and/or improvement(s) in
+      the <a href="https://github.com/alire-project/alire/src/alr">GitHub
+      repository.</a>
+  </small>
+ </div>
+  <div class="doc_content" markdown="1">
+
+ <!-- All the empty lines below, as well as the absence of indentation, seem to
+   be required for a correct parsing of the markdown files -->
+
+{% include_relative alr.md %}
+
+  </div>
+ </div>
+</div>

update-gh-pages.sh

@@ -65,6 +65,11 @@ cp alire/doc/* docs/
 # Append the built-ins config doc generated from the tool
 alr --no-tty config --builtins-doc >> docs/configuration.md
 
+# Add the `alr` help page
+# Substitution is needed because <placeholder> from messages are interpreted by Jekyll
+# TODO This can be removed if all these <placeholders> are quoted as `code`.
+alr dev --markdown-help | sed 's/</`<`/g; s/>/`>`/g' > docs/alr.md
+
 # Cleanup alire repo
 rm -rf alire/