forks/apenwarr-redo
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
apenwarr-redo/mkdocs.yml

72 lines
2 KiB
YAML
Raw Normal View History

First cookbook example for the docs: Hello World in C.
2018-11-24 14:36:02 -05:00
site_name: "redo: a recursive build system"
mkdocs: include additional hljs languages. 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
2019-02-12 16:32:30 -05:00
theme:
name: readthedocs
hljs_languages:
- python
- r
- shell
- tex
Directory reorg: move code into redo/, generate binaries in bin/. 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'.
2018-12-03 21:39:15 -05:00
docs_dir: docs
site_dir: docs.out
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.
2018-11-15 23:59:22 -05:00
strict: true
Even more doc cleanups.
2018-11-26 17:32:19 -05:00
repo_url: https://github.com/apenwarr/redo
Directory reorg: move code into redo/, generate binaries in bin/. 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'.
2018-12-03 21:39:15 -05:00
edit_uri: edit/master/docs
First cookbook example for the docs: Hello World in C.
2018-11-24 14:36:02 -05:00
extra_javascript:
- fetchcode.js
Docs: format inline <code> blocks better. 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.
2018-11-29 14:50:24 -05:00
extra_css:
- extra_style.css
mkdocs: enforce sufficiently new version, and use mkdocs-exclude. 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.
2019-01-08 01:32:16 -05:00
plugins:
- exclude:
glob:
cookbook/container: example of building+running docker containers. 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.
2019-01-02 23:46:01 -05:00
- cookbook/container/simple/*
- cookbook/container/debdownload/*
- cookbook/container/debootstrap/*
- cookbook/container/debian/*
mkdocs: exclude more generated files from cookbook/container.
2019-02-20 19:18:02 -05:00
- cookbook/container/libs/*
cookbook/container: example of building+running docker containers. 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.
2019-01-02 23:46:01 -05:00
- cookbook/container/*.fakeroot
mkdocs: exclude more generated files from cookbook/container.
2019-02-20 19:18:02 -05:00
- cookbook/container/*.image
- cookbook/container/*.initrd
- cookbook/container/*.layer
- cookbook/container/*.list
docs/cookbook/redoconf-simple: a simple redoconf C++ project. 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.)
2019-03-05 23:33:11 -05:00
- cookbook/*/out/*
- cookbook/*/out.*
mkdocs: enforce sufficiently new version, and use mkdocs-exclude. 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.
2019-01-08 01:32:16 -05:00
- "t/*"
mkdocs: exclude more generated file types. 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.
2019-02-23 06:47:59 -05:00
- "*.eps"
mkdocs: enforce sufficiently new version, and use mkdocs-exclude. 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.
2019-01-08 01:32:16 -05:00
- "*.gz"
mkdocs: exclude more generated file types. 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.
2019-02-23 06:47:59 -05:00
- "*.log"
mkdocs: enforce sufficiently new version, and use mkdocs-exclude. 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.
2019-01-08 01:32:16 -05:00
- "*.pdf"
- "*.ps"
mkdocs: exclude more generated file types. 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.
2019-02-23 06:47:59 -05:00
- "*.tar"
- "*.tmp"
mkdocs: enforce sufficiently new version, and use mkdocs-exclude. 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.
2019-01-08 01:32:16 -05:00
- "*.1"
regex:
- ".*~"
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.
2018-11-15 23:59:22 -05:00
mkdocs: enforce sufficiently new version, and use mkdocs-exclude. 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.
2019-01-08 01:32:16 -05:00
nav:
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.
2018-11-15 23:59:22 -05:00
- Introduction: index.md
Refactor the huge README.md into the more structured mkdocs. 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.
2018-11-16 03:13:33 -05:00
- Getting Started: GettingStarted.md
Even more doc cleanups.
2018-11-26 17:32:19 -05:00
- Contributing.md
Add Roadmap.md.
2018-12-03 01:45:36 -05:00
- Roadmap.md
First cookbook example for the docs: Hello World in C.
2018-11-24 14:36:02 -05:00
- Cookbook:
Even more doc cleanups.
2018-11-26 17:32:19 -05:00
- Hello World (hello.do, redo-ifchange): cookbook/hello/index.md
cookbook/container: example of building+running docker containers. 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.
2019-01-02 23:46:01 -05:00
- Text substitution (default.do, redo-always, redo-stamp): cookbook/defaults/index.md
- R plots and LaTeX to pdf (side effects, multiple outputs): cookbook/latex/index.md
- Docker and kvm containers (from scratch): cookbook/container/index.md
docs/cookbook/redoconf-simple: a simple redoconf C++ project. 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.)
2019-03-05 23:33:11 -05:00
- Portable C++ programs (using redoconf): cookbook/redoconf-simple/index.md
Refactor the huge README.md into the more structured mkdocs. 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.
2018-11-16 03:13:33 -05:00
- FAQ:
- Basics: FAQBasics.md
- Semantics: FAQSemantics.md
- Interop with make: FAQInterop.md
- Parallel Builds: FAQParallel.md
- Implementation Details: FAQImpl.md
Cookbook: add an example of using default.do for text processing.
2018-11-26 13:10:29 -05:00
- Reference Manual:
- redo(1): redo.md
- redo-ifchange(1): redo-ifchange.md
- redo-ifcreate(1): redo-ifcreate.md
- redo-always(1): redo-always.md
- redo-stamp(1): redo-stamp.md
- redo-sources(1): redo-sources.md
- redo-targets(1): redo-targets.md
- redo-ood(1): redo-ood.md
- redo-whichdo(1): redo-whichdo.md
- redo-log(1): redo-log.md
Reference in a new issue Copy permalink