docs: create SUMMARY.md automatically

docs/.gitignore

@@ -1,2 +1,3 @@
 book
 src/utils
+src/SUMMARY.md

docs/create_docs.py

@@ -1,12 +0,0 @@
-# Simple script to create the correct SUMMARY.md and other files
-# for the mdbook documentation.
-# Note: This will overwrite the existing files!
-
-import os
-
-with open('src/SUMMARY.md', 'w') as summary:
-    summary.write("# Summary\n\n")
-    summary.write("[Introduction](index.md)\n")
-    summary.write("* [Contributing](contributing.md)\n")
-    for d in sorted(os.listdir('../src/uu')):
-        summary.write(f"* [{d}](utils/{d}.md)\n")

docs/src/SUMMARY.md

@@ -1,108 +0,0 @@
-# Summary
-
-[Introduction](index.md)
-* [Installation](installation.md)
-* [Contributing](contributing.md)
-
-# Reference
-* [Multi-call binary](multicall.md)
-* [arch](utils/arch.md)
-* [base32](utils/base32.md)
-* [base64](utils/base64.md)
-* [basename](utils/basename.md)
-* [basenc](utils/basenc.md)
-* [cat](utils/cat.md)
-* [chcon](utils/chcon.md)
-* [chgrp](utils/chgrp.md)
-* [chmod](utils/chmod.md)
-* [chown](utils/chown.md)
-* [chroot](utils/chroot.md)
-* [cksum](utils/cksum.md)
-* [comm](utils/comm.md)
-* [cp](utils/cp.md)
-* [csplit](utils/csplit.md)
-* [cut](utils/cut.md)
-* [date](utils/date.md)
-* [dd](utils/dd.md)
-* [df](utils/df.md)
-* [dircolors](utils/dircolors.md)
-* [dirname](utils/dirname.md)
-* [du](utils/du.md)
-* [echo](utils/echo.md)
-* [env](utils/env.md)
-* [expand](utils/expand.md)
-* [expr](utils/expr.md)
-* [factor](utils/factor.md)
-* [false](utils/false.md)
-* [fmt](utils/fmt.md)
-* [fold](utils/fold.md)
-* [groups](utils/groups.md)
-* [hashsum](utils/hashsum.md)
-* [head](utils/head.md)
-* [hostid](utils/hostid.md)
-* [hostname](utils/hostname.md)
-* [id](utils/id.md)
-* [install](utils/install.md)
-* [join](utils/join.md)
-* [kill](utils/kill.md)
-* [link](utils/link.md)
-* [ln](utils/ln.md)
-* [logname](utils/logname.md)
-* [ls](utils/ls.md)
-* [mkdir](utils/mkdir.md)
-* [mkfifo](utils/mkfifo.md)
-* [mknod](utils/mknod.md)
-* [mktemp](utils/mktemp.md)
-* [more](utils/more.md)
-* [mv](utils/mv.md)
-* [nice](utils/nice.md)
-* [nl](utils/nl.md)
-* [nohup](utils/nohup.md)
-* [nproc](utils/nproc.md)
-* [numfmt](utils/numfmt.md)
-* [od](utils/od.md)
-* [paste](utils/paste.md)
-* [pathchk](utils/pathchk.md)
-* [pinky](utils/pinky.md)
-* [pr](utils/pr.md)
-* [printenv](utils/printenv.md)
-* [printf](utils/printf.md)
-* [ptx](utils/ptx.md)
-* [pwd](utils/pwd.md)
-* [readlink](utils/readlink.md)
-* [realpath](utils/realpath.md)
-* [relpath](utils/relpath.md)
-* [rm](utils/rm.md)
-* [rmdir](utils/rmdir.md)
-* [runcon](utils/runcon.md)
-* [seq](utils/seq.md)
-* [shred](utils/shred.md)
-* [shuf](utils/shuf.md)
-* [sleep](utils/sleep.md)
-* [sort](utils/sort.md)
-* [split](utils/split.md)
-* [stat](utils/stat.md)
-* [stdbuf](utils/stdbuf.md)
-* [sum](utils/sum.md)
-* [sync](utils/sync.md)
-* [tac](utils/tac.md)
-* [tail](utils/tail.md)
-* [tee](utils/tee.md)
-* [test](utils/test.md)
-* [timeout](utils/timeout.md)
-* [touch](utils/touch.md)
-* [tr](utils/tr.md)
-* [true](utils/true.md)
-* [truncate](utils/truncate.md)
-* [tsort](utils/tsort.md)
-* [tty](utils/tty.md)
-* [uname](utils/uname.md)
-* [unexpand](utils/unexpand.md)
-* [uniq](utils/uniq.md)
-* [unlink](utils/unlink.md)
-* [uptime](utils/uptime.md)
-* [users](utils/users.md)
-* [wc](utils/wc.md)
-* [who](utils/who.md)
-* [whoami](utils/whoami.md)
-* [yes](utils/yes.md)

docs/theme/head.hbs

@@ -10,4 +10,7 @@
         top: 1em;
         right: 0;
     }
+    dd > p {
+        margin-top: 0.2em;
+    }
 </style>

src/bin/uudoc.rs

@@ -1,7 +1,5 @@
 // This file is part of the uutils coreutils package.
 //
-// (c) Michael Gehring <mg@ebfe.org>
-//
 // For the full copyright and license information, please view the LICENSE
 // file that was distributed with this source code.
 
@@ -9,74 +7,97 @@ use clap::App;
 use std::collections::hash_map::HashMap;
 use std::ffi::OsString;
 use std::fs::File;
-use std::io::Write;
+use std::io::{self, Write};
 
 include!(concat!(env!("OUT_DIR"), "/uutils_map.rs"));
 
-fn main() -> std::io::Result<()> {
+fn main() -> io::Result<()> {
     let utils = util_map::<Box<dyn Iterator<Item = OsString>>>();
     match std::fs::create_dir("docs/src/utils/") {
         Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(()),
         x => x,
     }?;
-    for (name, (_, app)) in utils {
+
+    let mut summary = File::create("docs/src/SUMMARY.md")?;
+
+    let _ = write!(
+        summary,
+        "# Summary\n\
+        \n\
+        [Introduction](index.md)\n\
+        * [Installation](installation.md)\n\
+        * [Contributing](contributing.md)\n\
+        \n\
+        # Reference\n\
+        * [Multi-call binary](multicall.md)\n",
+    );
+
+    let mut utils = utils.iter().collect::<Vec<_>>();
+    utils.sort();
+    for (&name, (_, app)) in utils {
+        if name == "[" {
+            continue;
+        }
         let p = format!("docs/src/utils/{}.md", name);
         if let Ok(f) = File::create(&p) {
-            write_markdown(f, &mut app(), name);
+            write_markdown(f, &mut app(), name)?;
             println!("Wrote to '{}'", p);
         } else {
             println!("Error writing to {}", p);
         }
+        write!(summary, "* [{0}](utils/{0}.md)\n", name)?
     }
     Ok(())
 }
 
-fn write_markdown(mut w: impl Write, app: &mut App, name: &str) {
+fn write_markdown(mut w: impl Write, app: &mut App, name: &str) -> io::Result<()> {
-    let _ = write!(w, "# {}\n\n", name);
+    write!(w, "# {}\n\n", name)?;
-    write_version(&mut w, app);
+    write_version(&mut w, app)?;
-    write_usage(&mut w, app, name);
+    write_usage(&mut w, app, name)?;
-    write_summary(&mut w, app);
+    write_description(&mut w, app)?;
-    write_options(&mut w, app);
+    write_options(&mut w, app)
 }
 
-fn write_version(w: &mut impl Write, app: &App) {
+fn write_version(w: &mut impl Write, app: &App) -> io::Result<()> {
-    let _ = writeln!(
+    writeln!(
         w,
         "<div class=\"version\">version: {}</div>",
         app.render_version().split_once(' ').unwrap().1
-    );
+    )
 }
 
-fn write_usage(w: &mut impl Write, app: &mut App, name: &str) {
+fn write_usage(w: &mut impl Write, app: &mut App, name: &str) -> io::Result<()> {
-    let _ = writeln!(w, "\n```");
+    writeln!(w, "\n```")?;
     let mut usage: String = app.render_usage().lines().nth(1).unwrap().trim().into();
     usage = usage.replace(app.get_name(), name);
-    let _ = writeln!(w, "{}", usage);
+    writeln!(w, "{}", usage)?;
-    let _ = writeln!(w, "```");
+    writeln!(w, "```")
 }
 
-fn write_summary(w: &mut impl Write, app: &App) {
+fn write_description(w: &mut impl Write, app: &App) -> io::Result<()> {
     if let Some(about) = app.get_long_about().or_else(|| app.get_about()) {
-        let _ = writeln!(w, "{}", about);
+        writeln!(w, "{}", about)
+    } else {
+        Ok(())
     }
 }
 
-fn write_options(w: &mut impl Write, app: &App) {
+fn write_options(w: &mut impl Write, app: &App) -> io::Result<()> {
-    let _ = writeln!(w, "<h2>Options</h2>");
+    writeln!(w, "<h2>Options</h2>")?;
-    let _ = write!(w, "<dl>");
+    write!(w, "<dl>")?;
     for arg in app.get_arguments() {
-        let _ = write!(w, "<dt>");
+        write!(w, "<dt>")?;
         let mut first = true;
         for l in arg.get_long_and_visible_aliases().unwrap_or_default() {
             if !first {
-                let _ = write!(w, ", ");
+                write!(w, ", ")?;
             } else {
                 first = false;
             }
-            let _ = write!(w, "<code>");
+            write!(w, "<code>")?;
-            let _ = write!(w, "--{}", l);
+            write!(w, "--{}", l)?;
             if let Some(names) = arg.get_value_names() {
-                let _ = write!(
+                write!(
                     w,
                     "={}",
                     names
@@ -84,20 +105,20 @@ fn write_options(w: &mut impl Write, app: &App) {
                         .map(|x| format!("&lt;{}&gt;", x))
                         .collect::<Vec<_>>()
                         .join(" ")
-                );
+                )?;
             }
-            let _ = write!(w, "</code>");
+            write!(w, "</code>")?;
         }
         for s in arg.get_short_and_visible_aliases().unwrap_or_default() {
             if !first {
-                let _ = write!(w, ", ");
+                write!(w, ", ")?;
             } else {
                 first = false;
             }
-            let _ = write!(w, "<code>");
+            write!(w, "<code>")?;
-            let _ = write!(w, "-{}", s);
+            write!(w, "-{}", s)?;
             if let Some(names) = arg.get_value_names() {
-                let _ = write!(
+                write!(
                     w,
                     " {}",
                     names
@@ -105,12 +126,12 @@ fn write_options(w: &mut impl Write, app: &App) {
                         .map(|x| format!("&lt;{}&gt;", x))
                         .collect::<Vec<_>>()
                         .join(" ")
-                );
+                )?;
             }
-            let _ = write!(w, "</code>");
+            write!(w, "</code>")?;
         }
-        let _ = writeln!(w, "</dt>");
+        writeln!(w, "</dt>")?;
-        let _ = writeln!(w, "<dd>{}</dd>", arg.get_help().unwrap_or_default());
+        writeln!(w, "<dd>\n\n{}\n\n</dd>", arg.get_help().unwrap_or_default())?;
     }
-    let _ = writeln!(w, "</dl>");
+    writeln!(w, "</dl>")
 }