Migrate "manual" style documentation to mdbook.
We discussed this today. AIUI, the initial plan is:
- Leave introduction.md in place for now, but plan to migrate pieces of it later.
- Create a new
book
top-level directory with an mdbook instance in it. Start writing the book. - Leave reference.md alone permanently.
- Figure out how to host the rendered book at some point.
Revised plan (15 May):
-
Create "book" with an mdbook instance. !350 (merged) -
Add CI support for building the mdbook instance. !350 (merged) -
Cause gitlab to deploy the book whenever it is merged to main. !350 (merged) -
Robustness improvements to mdbook-build and related scripts !371 (merged) - Add usage documentation/comments
- Reject unknown options
-
Move text from introduction.md to mdbook. !372 (merged) - And add building/editing instructions to
HACKING.md
- And add appropriate cross-links from docs.rs documentation to mdbook.
- And rename from "introduction" to guide.
- And add building/editing instructions to
-
Add intermediate index.html files to generated page.
At this point, I would prefer to just work on the documentation for a while.
Later we would want to:
-
Add facilities to build local link-adjusted versions of the mdbook and the rustdoc, and to validate that the links are sensible. -
Purchase a domain to use instead of diziet.pages.torproject.net; add a redirect or a vhost. -
Arrange for per-tag versions of the book to exist and link to appropriate corresponding versions of the rustdoc. -
Combine any duplicated logic wrt link checking with torspec mdbook code
Edited by Ian Jackson