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

_config.yml

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

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,17 @@ 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
+alr dev --help-doc-markdown > docs/alr.md
+
+# Warn if there are any unquoted <placeholder> from messages, since they are
+# incorrectly evaluated by Jekyll and the format will be broken.
+# When this happens, the probable solution is to wrap these placeholders with
+# CLIC.Formatter.Terminal
+if grep -Hn '<[a-z_]*>' docs/alr.md | grep -v '`' ; then
+    echo 'Warning: <placeholder> found not quoted as `code` in docs/alr.md' >&2
+fi
+
 # Cleanup alire repo
 rm -rf alire/