Automatic mdBook Documentation

.vscode/cspell.dictionaries/workspace.wordlist.txt

@@ -25,6 +25,7 @@ getrandom
 globset
 itertools
 lscolors
+mdbook
 memchr
 multifilereader
 onig
@@ -322,6 +323,7 @@ ucommand
 utmpx
 uucore
 uucore_procs
+uudoc
 uumain
 uutil
 uutils

Cargo.toml

@@ -9,6 +9,7 @@ version = "0.0.12"
 authors = ["uutils developers"]
 license = "MIT"
 description = "coreutils ~ GNU coreutils (updated); implemented as universal (cross-platform) utils, written in Rust"
+default-run = "coreutils"
 
 homepage = "https:/uutils/coreutils"
 repository = "https:/uutils/coreutils"
@@ -389,3 +390,7 @@ unix_socket = "0.5.0"
 [[bin]]
 name = "coreutils"
 path = "src/bin/coreutils.rs"
+
+[[bin]]
+name = "uudoc"
+path = "src/bin/uudoc.rs"

GNUmakefile

@@ -279,10 +279,7 @@ endif
 build-coreutils:
  ${CARGO} build ${CARGOFLAGS} --features "${EXES}" ${PROFILE_CMD} --no-default-features
 
-build-manpages:
- cd $(DOCSDIR) && $(MAKE) man
-
-build: build-coreutils build-pkgs build-manpages
+build: build-coreutils build-pkgs
 
 $(foreach test,$(filter-out $(SKIP_UTILS),$(PROGS)),$(eval $(call TEST_BUSYBOX,$(test))))
 
@@ -330,14 +327,11 @@ ifeq (${MULTICALL}, y)
  cd $(INSTALLDIR_BIN) && $(foreach prog, $(filter-out coreutils, $(INSTALLEES)), \
  ln -fs $(PROG_PREFIX)coreutils $(PROG_PREFIX)$(prog) &&) :
  $(if $(findstring test,$(INSTALLEES)), cd $(INSTALLDIR_BIN) && ln -fs $(PROG_PREFIX)coreutils $(PROG_PREFIX)[)
- cat $(DOCSDIR)/_build/man/coreutils.1 | gzip > $(INSTALLDIR_MAN)/$(PROG_PREFIX)coreutils.1.gz
 else
  $(foreach prog, $(INSTALLEES), \
  $(INSTALL) $(BUILDDIR)/$(prog) $(INSTALLDIR_BIN)/$(PROG_PREFIX)$(prog);)
  $(if $(findstring test,$(INSTALLEES)), $(INSTALL) $(BUILDDIR)/test $(INSTALLDIR_BIN)/$(PROG_PREFIX)[)
 endif
- $(foreach man, $(filter $(INSTALLEES), $(basename $(notdir $(wildcard $(DOCSDIR)/_build/man/*)))), \
- cat $(DOCSDIR)/_build/man/$(man).1 | gzip > $(INSTALLDIR_MAN)/$(PROG_PREFIX)$(man).1.gz &&) :
  mkdir -p $(DESTDIR)$(PREFIX)/share/zsh/site-functions
  mkdir -p $(DESTDIR)$(PREFIX)/share/bash-completion/completions
  mkdir -p $(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d
@@ -359,4 +353,4 @@ endif
  rm -f $(addprefix $(DESTDIR)$(PREFIX)/share/fish/vendor_completions.d/$(PROG_PREFIX),$(addsuffix .fish,$(PROGS)))
  rm -f $(addprefix $(INSTALLDIR_MAN)/$(PROG_PREFIX),$(addsuffix .1.gz,$(PROGS)))
 
-.PHONY: all build build-coreutils build-pkgs build-docs test distclean clean busytest install uninstall
+.PHONY: all build build-coreutils build-pkgs test distclean clean busytest install uninstall

README.md

@@ -29,6 +29,7 @@ have other issues.
 Rust provides a good, platform-agnostic way of writing systems utilities that are easy
 to compile anywhere, and this is as good a way as any to try and learn it.
 
+<!-- ANCHOR: installation (this mark is needed for mdbook) -->
 ## Requirements
 
 * Rust (`cargo`, `rustc`)
@@ -252,6 +253,7 @@ To uninstall from a custom parent directory:
 # DESTDIR is also supported
 $ make PREFIX=/my/path uninstall
 ```
+<!-- ANCHOR_END: installation (this mark is needed for mdbook) -->
 
 ## Test Instructions
 

docs/.gitignore

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

docs/book.toml

@@ -0,0 +1,9 @@
+[book]
+authors = ["uutils contributors"]
+language = "en"
+multilingual = false
+src = "src"
+title = "uutils Documentation"
+
+[output.html]
+git-repository-url = "https:/rust-lang/cargo/tree/master/src/doc/src"

docs/src/contributing.md

@@ -0,0 +1 @@
+{{ #include ../../CONTRIBUTING.md }}

docs/src/index.md

@@ -0,0 +1,20 @@
+# uutils Coreutils Documentation
+
+uutils is an attempt at writing universal (as in cross-platform) CLI
+utilities in [Rust](https://www.rust-lang.org). It is available for
+Linux, Windows, Mac and other platforms.
+
+The API reference for `uucore`, the library of functions shared between
+various utils, is hosted at at
+[docs.rs](https://docs.rs/uucore/latest/uucore/).
+
+uutils is licensed under the [MIT License](https:/uutils/coreutils/blob/main/LICENSE).
+
+## Useful links
+* [Releases](https:/uutils/coreutils/releases)
+* [Source Code](https:/uutils/coreutils)
+* [Issues](https:/uutils/coreutils/issues)
+* [Discord](https://discord.gg/wQVJbvJ)
+
+> Note: This manual is automatically generated from the source code and is
+> a work in progress.

docs/src/installation.md

@@ -0,0 +1,3 @@
+# Installation
+
+{{#include ../../README.md:installation }}

docs/src/multicall.md

@@ -0,0 +1,17 @@
+# Multi-call binary
+uutils includes a multi-call binary from which the utils can be invoked. This
+reduces the binary size of the binary and can be useful for portability.
+
+The first argument of the multi-call binary is the util to run, after which
+the regular arguments to the util can be passed.
+
+```shell
+coreutils [util] [util options]
+```
+
+The `--help` flag will print a list of available utils.
+
+## Example
+```
+coreutils ls -l
+```

docs/theme/head.hbs

@@ -0,0 +1,16 @@
+<style>
+ dd {
+ margin-bottom: 1em;
+ }
+ main {
+ position: relative;
+ }
+ .version {
+ position: absolute;
+ top: 1em;
+ right: 0;
+ }
+ dd > p {
+ margin-top: 0.2em;
+ }
+</style>

src/bin/uudoc.rs

@@ -0,0 +1,137 @@
+// This file is part of the uutils coreutils package.
+//
+// For the full copyright and license information, please view the LICENSE
+// file that was distributed with this source code.
+
+use clap::App;
+use std::collections::hash_map::HashMap;
+use std::ffi::OsString;
+use std::fs::File;
+use std::io::{self, Write};
+
+include!(concat!(env!("OUT_DIR"), "/uutils_map.rs"));
+
+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,
+ }?;
+
+ 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)?;
+ println!("Wrote to '{}'", p);
+ } else {
+ println!("Error writing to {}", p);
+ }
+ writeln!(summary, "* [{0}](utils/{0}.md)", name)?
+ }
+ Ok(())
+}
+
+fn write_markdown(mut w: impl Write, app: &mut App, name: &str) -> io::Result<()> {
+ write!(w, "# {}\n\n", name)?;
+ write_version(&mut w, app)?;
+ write_usage(&mut w, app, name)?;
+ write_description(&mut w, app)?;
+ write_options(&mut w, app)
+}
+
+fn write_version(w: &mut impl Write, app: &App) -> io::Result<()> {
+ 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) -> io::Result<()> {
+ writeln!(w, "\n```")?;
+ let mut usage: String = app.render_usage().lines().nth(1).unwrap().trim().into();
+ usage = usage.replace(app.get_name(), name);
+ writeln!(w, "{}", usage)?;
+ writeln!(w, "```")
+}
+
+fn write_description(w: &mut impl Write, app: &App) -> io::Result<()> {
+ if let Some(about) = app.get_long_about().or_else(|| app.get_about()) {
+ writeln!(w, "{}", about)
+ } else {
+ Ok(())
+ }
+}
+
+fn write_options(w: &mut impl Write, app: &App) -> io::Result<()> {
+ writeln!(w, "<h2>Options</h2>")?;
+ write!(w, "<dl>")?;
+ for arg in app.get_arguments() {
+ write!(w, "<dt>")?;
+ let mut first = true;
+ for l in arg.get_long_and_visible_aliases().unwrap_or_default() {
+ if !first {
+ write!(w, ", ")?;
+ } else {
+ first = false;
+ }
+ write!(w, "<code>")?;
+ write!(w, "--{}", l)?;
+ if let Some(names) = arg.get_value_names() {
+ write!(
+ w,
+ "={}",
+ names
+ .iter()
+ .map(|x| format!("&lt;{}&gt;", x))
+ .collect::<Vec<_>>()
+ .join(" ")
+ )?;
+ }
+ write!(w, "</code>")?;
+ }
+ for s in arg.get_short_and_visible_aliases().unwrap_or_default() {
+ if !first {
+ write!(w, ", ")?;
+ } else {
+ first = false;
+ }
+ write!(w, "<code>")?;
+ write!(w, "-{}", s)?;
+ if let Some(names) = arg.get_value_names() {
+ write!(
+ w,
+ " {}",
+ names
+ .iter()
+ .map(|x| format!("&lt;{}&gt;", x))
+ .collect::<Vec<_>>()
+ .join(" ")
+ )?;
+ }
+ write!(w, "</code>")?;
+ }
+ writeln!(w, "</dt>")?;
+ writeln!(w, "<dd>\n\n{}\n\n</dd>", arg.get_help().unwrap_or_default())?;
+ }
+ writeln!(w, "</dl>")
+}

src/uu/sum/src/sum.rs

@@ -19,9 +19,9 @@ use uucore::error::{FromIo, UResult, USimpleError};
 use uucore::InvalidEncodingHandling;
 
 static NAME: &str = "sum";
-static USAGE: &str =
- "[OPTION]... [FILE]...\nWith no FILE, or when FILE is -, read standard input.";
-static SUMMARY: &str = "Checksum and count the blocks in a file.";
+static USAGE: &str = "sum [OPTION]... [FILE]...";
+static SUMMARY: &str = "Checksum and count the blocks in a file.\n\
+ With no FILE, or when FILE is -, read standard input.";
 
 fn bsd_sum(mut reader: Box<dyn Read>) -> (usize, u16) {
  let mut buf = [0; 1024];