This is a little simpler than the docs/cookbook/c project, which
doesn't actually have a doc yet because there was too much to explain.
I think I might make that a follow-on cookbook chapter, for people who
have read this simple one.
I think this doc is maybe a little too long; I intended it to be
"here's what you do to get started" but it turned into "here's what you
do to get started, and why it works, in excruciating detail." Not quite
sure how to fix.
(Also updated some other parts of the docs to refer to redoconf as a
real thing now instead of a "maybe someone should write this" thing.)
These files can appear/disappear during a parallel build, which
confuses mkdocs when it tries to refer to them, even though we never
wanted them in the docs anyway.
We upgraded mkdocs earlier to support some useful features (like the
mkdocs-exclude plugin), but that one changes the highlight.js
configuration to include fewer languages by default. Specify the
additional ones we want to include.
Reported-by: @DRMacIver on twitter
This got... long... and complicated. But I think it's a really good
demonstration of getting redo to do complicated things elegantly. At
least, I hope it is.
We want to use the mkdocs-exclude plugin, which lets us exclude
particular files from the output directory. But plugins aren't
available in the debian-stable version of mkdocs, so ensure that we're
running a sufficiently new version. If we aren't, gracefully just skip
building the documentation.
It's time to start preparing for a version of redo that doesn't work
unless we build it first (because it will rely on C modules, and
eventually be rewritten in C altogether).
To get rolling, remove the old-style symlinks to the main programs, and
rename those programs from redo-*.py to redo/cmd_*.py. We'll also move
all library functions into the redo/ dir, which is a more python-style
naming convention.
Previously, install.do was generating wrappers for installing in
/usr/bin, which extend sys.path and then import+run the right file.
This made "installed" redo work quite differently from running redo
inside its source tree. Instead, let's always generate the wrappers in
bin/, and not make anything executable except those wrappers.
Since we're generating wrappers anyway, let's actually auto-detect the
right version of python for the running system; distros can't seem to
agree on what to call their python2 binaries (sigh). We'll fill in the
right #! shebang lines. Since we're doing that, we can stop using
/usr/bin/env, which will a) make things slightly faster, and b) let us
use "python -S", which tells python not to load a bunch of extra crap
we're not using, thus improving startup times.
Annoyingly, we now have to build redo using minimal/do, then run the
tests using bin/redo. To make this less annoying, we add a toplevel
./do script that knows the right steps, and a Makefile (whee!) for
people who are used to typing 'make' and 'make test' and 'make clean'.
It seems like we're using these differently than most readthedocs.org
users. Remove the borders and padding so they work better inline, and
prevent confusing word wraps.
This shows how to dynamically generate a plot in R+ggplot2, then embed
it into a latex document, and compile it to pdf, all with proper
autodependencies.
I also cleaned up the installation section and added links to various
competing redo implementations.
The new README.md is basically just link to the docs on
readthedocs.org, and a link to the mailing list.
These docs need a *lot* more work, but this is enough of an improvement
that I'll commit it anyway for now.
