From 4cf156e9301e761eac74ad1e16695d93f9c57d8c Mon Sep 17 00:00:00 2001 From: Avery Pennarun Date: Thu, 15 Nov 2018 23:59:22 -0500 Subject: [PATCH] Generate a basic documentation website with the mkdocs toolkit. No content yet other than man pages. To make the man pages render nicely in mkdocs, I removed the static %-headers and put the code for them into default.md.tmp.do instead. That way, the raw input redo-*.md files will look right in mkdocs. --- .gitignore | 1 + Documentation/.gitignore | 2 ++ Documentation/all.do | 8 +++----- Documentation/clean.do | 2 +- Documentation/default.md.tmp.do | 6 +++++- Documentation/doc.list.do | 3 +++ Documentation/index.md | 1 + Documentation/mkdocs.do | 9 +++++++++ Documentation/mkdocs.yml | 18 ++++++++++++++++++ Documentation/redo-always.md | 4 ---- Documentation/redo-ifchange.md | 4 ---- Documentation/redo-ifcreate.md | 4 ---- Documentation/redo-ood.md | 4 ---- Documentation/redo-sources.md | 4 ---- Documentation/redo-stamp.md | 4 ---- Documentation/redo-targets.md | 4 ---- Documentation/redo-whichdo.md | 8 ++------ Documentation/redo.md | 4 ---- 18 files changed, 45 insertions(+), 45 deletions(-) create mode 100644 Documentation/doc.list.do create mode 100644 Documentation/index.md create mode 100644 Documentation/mkdocs.do create mode 100644 Documentation/mkdocs.yml diff --git a/.gitignore b/.gitignore index ccaf84b..ea31ad9 100644 --- a/.gitignore +++ b/.gitignore @@ -8,3 +8,4 @@ *.tmp /redo-sh *.did +/website diff --git a/Documentation/.gitignore b/Documentation/.gitignore index e89be4c..101eb2a 100644 --- a/Documentation/.gitignore +++ b/Documentation/.gitignore @@ -1,3 +1,5 @@ *.1 /md-to-man *.html +*.man.md +*.list diff --git a/Documentation/all.do b/Documentation/all.do index f433edc..51e7edd 100644 --- a/Documentation/all.do +++ b/Documentation/all.do @@ -1,5 +1,3 @@ -/bin/ls *.md t/*.md | -sed 's/\.md/.1/' | -xargs redo-ifchange - -redo-always +redo-ifchange doc.list +sed 's/\.md/.1/' + % $DATE +EOF diff --git a/Documentation/doc.list.do b/Documentation/doc.list.do new file mode 100644 index 0000000..28c8b2c --- /dev/null +++ b/Documentation/doc.list.do @@ -0,0 +1,3 @@ +ls redo*.md t/*.md >$3 +redo-always +redo-stamp <$3 diff --git a/Documentation/index.md b/Documentation/index.md new file mode 100644 index 0000000..cd08755 --- /dev/null +++ b/Documentation/index.md @@ -0,0 +1 @@ +Hello world! diff --git a/Documentation/mkdocs.do b/Documentation/mkdocs.do new file mode 100644 index 0000000..86433d2 --- /dev/null +++ b/Documentation/mkdocs.do @@ -0,0 +1,9 @@ +redo-ifchange doc.list +xargs redo-ifchange mkdocs.yml /dev/null 2>/dev/null; then + mkdocs build +else + echo "Warning: mkdocs is missing; can't generate website." >&2 + redo-ifcreate /usr/bin/mkdocs +fi diff --git a/Documentation/mkdocs.yml b/Documentation/mkdocs.yml new file mode 100644 index 0000000..3589df3 --- /dev/null +++ b/Documentation/mkdocs.yml @@ -0,0 +1,18 @@ +site_name: redo build system +theme: readthedocs +docs_dir: . +site_dir: ../website +strict: true + +pages: + - Introduction: index.md + - Man Pages: + - redo: redo.md + - redo-ifchange: redo-ifchange.md + - redo-ifcreate: redo-ifcreate.md + - redo-always: redo-always.md + - redo-stamp: redo-stamp.md + - redo-sources: redo-sources.md + - redo-targets: redo-targets.md + - redo-ood: redo-ood.md + - redo-whichdo: redo-whichdo.md diff --git a/Documentation/redo-always.md b/Documentation/redo-always.md index a48da69..e9623cf 100644 --- a/Documentation/redo-always.md +++ b/Documentation/redo-always.md @@ -1,7 +1,3 @@ -% redo-always(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-always - mark the current target as always needing to be rebuilt diff --git a/Documentation/redo-ifchange.md b/Documentation/redo-ifchange.md index 5c8dcd0..3609a25 100644 --- a/Documentation/redo-ifchange.md +++ b/Documentation/redo-ifchange.md @@ -1,7 +1,3 @@ -% redo-ifchange(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-ifchange - rebuild target files when source files have changed diff --git a/Documentation/redo-ifcreate.md b/Documentation/redo-ifcreate.md index 12afd16..f2f9e96 100644 --- a/Documentation/redo-ifcreate.md +++ b/Documentation/redo-ifcreate.md @@ -1,7 +1,3 @@ -% redo-ifcreate(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-ifcreate - rebuild the current target if source files are created diff --git a/Documentation/redo-ood.md b/Documentation/redo-ood.md index b425378..629d48e 100644 --- a/Documentation/redo-ood.md +++ b/Documentation/redo-ood.md @@ -1,7 +1,3 @@ -% redo-ood(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-ood - print the list of out-of-date redo targets diff --git a/Documentation/redo-sources.md b/Documentation/redo-sources.md index d6c3fe4..64538e1 100644 --- a/Documentation/redo-sources.md +++ b/Documentation/redo-sources.md @@ -1,7 +1,3 @@ -% redo-sources(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-sources - print the list of all known redo sources diff --git a/Documentation/redo-stamp.md b/Documentation/redo-stamp.md index b723a96..e7e5977 100644 --- a/Documentation/redo-stamp.md +++ b/Documentation/redo-stamp.md @@ -1,7 +1,3 @@ -% redo-stamp(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-stamp - detect if the current target has meaningfully changed diff --git a/Documentation/redo-targets.md b/Documentation/redo-targets.md index e1af075..00dc531 100644 --- a/Documentation/redo-targets.md +++ b/Documentation/redo-targets.md @@ -1,7 +1,3 @@ -% redo-targets(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-targets - print the list of all known redo targets diff --git a/Documentation/redo-whichdo.md b/Documentation/redo-whichdo.md index e602676..d7843e0 100644 --- a/Documentation/redo-whichdo.md +++ b/Documentation/redo-whichdo.md @@ -1,7 +1,3 @@ -% redo-ifchange(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo-whichdo - show redo's search path for a .do file @@ -34,7 +30,7 @@ search path has been exhausted (and printed). Here's a typical search path for a source file (`x/y/a.b.o`). Because the filename contains two dots (.), at each level of the hierarchy, `redo` needs to search `default.b.o.do`, `default.o.do`, and `default.do`. - +```sh $ redo-whichdo x/y/a.b.o; echo $? x/y/a.b.o.do @@ -47,7 +43,7 @@ to search `default.b.o.do`, `default.o.do`, and `default.do`. default.b.o.do default.o.do 0 - +``` You might use `redo-whichdo` to delegate from one .do script to another, using code like the following. This gets a little tricky because not only are you finding a new .do file, but you have `cd` to the .do file diff --git a/Documentation/redo.md b/Documentation/redo.md index f4625c3..e508ada 100644 --- a/Documentation/redo.md +++ b/Documentation/redo.md @@ -1,7 +1,3 @@ -% redo(1) Redo %VERSION% -% Avery Pennarun -% %DATE% - # NAME redo - rebuild target files when source files have changed