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.9"
 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,2 @@
+book
+src/utils

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/create_docs.py

@@ -0,0 +1,12 @@
+# 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

@@ -0,0 +1,108 @@
+# 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/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/0.0.12/uucore/).
+
+uutils is licensed under the [MIT License](https:/uutils/coreutils/LICENSE.md).
+
+## 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,13 @@
+<style>
+ dd {
+ margin-bottom: 1em;
+ }
+ main {
+ position: relative;
+ }
+ .version {
+ position: absolute;
+ top: 1em;
+ right: 0;
+ }
+</style>