From d21160868c3767722e43fed8da60d2bf1595f87d Mon Sep 17 00:00:00 2001 From: hinto-janai Date: Wed, 29 May 2024 20:19:46 -0400 Subject: [PATCH] books: add skeleton and docs (#141) * update `books/` * update CONTRIBUTING.md * .gitignore: ignore built books * add dummy `books/architecture/` * remove some changes from CONTRIBUTING.md out of scope, will be in another PR * add docs/books to LICENSE * formatting --- .gitignore | 1 + CONTRIBUTING.md | 5 +++++ LICENSE.md => LICENSE | 3 +++ books/README.md | 29 ++++++++++++++++++++++++++++- books/architecture/README.md | 7 ++++++- books/architecture/book.toml | 19 +++++++++++++++++++ books/architecture/src/SUMMARY.md | 3 +++ books/architecture/src/todo.md | 1 + books/protocol/README.md | 7 ++++++- 9 files changed, 72 insertions(+), 3 deletions(-) rename LICENSE.md => LICENSE (78%) create mode 100644 books/architecture/book.toml create mode 100644 books/architecture/src/SUMMARY.md create mode 100644 books/architecture/src/todo.md diff --git a/.gitignore b/.gitignore index 5b939ef9..3c385b68 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,4 @@ target/ .vscode monerod +books/*/book diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f27de2af..33b87809 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -64,3 +64,8 @@ This section is primarily targeted at maintainers. Most contributors aren't able [I-]: https://github.com/Cuprate/cuprate/labels?q=I [O-]: https://github.com/Cuprate/cuprate/labels?q=O [P-]: https://github.com/Cuprate/cuprate/labels?q=P + +## Books +Cuprate has various documentation books whose source files live in [`books/`](https://github.com/Cuprate/cuprate/tree/main/books). + +Please contribute if you found a mistake! The files are mostly [markdown](https://wikipedia.org/wiki/Markdown) files and can be easily edited. See the `books/` directory for more information. diff --git a/LICENSE.md b/LICENSE similarity index 78% rename from LICENSE.md rename to LICENSE index 002555e1..c8f836ad 100644 --- a/LICENSE.md +++ b/LICENSE @@ -3,3 +3,6 @@ depending on the crate in question. Each crate declares their license in their `Cargo.toml`. Additionally, a full copy of both licenses are included in the root of this repository for reference. These copies should be provided with any distribution of a crate, as per the respective license's terms. + +All documentation, including the books in the `books/` directory, is licensed +under the MIT license. diff --git a/books/README.md b/books/README.md index 46409041..c2b079e4 100644 --- a/books/README.md +++ b/books/README.md @@ -1 +1,28 @@ -# TODO +## Books +This directory contains the source files for Cuprate's various books. + +The source files are edited here, and published in other repositories, see: +- [Cuprate's architecture book](https://github.com/Cuprate/architecture-book) +- [Cuprate's protocol book](https://github.com/Cuprate/monero-book) + +## Build tools +Building the book(s) requires [Rust's cargo tool](https://doc.rust-lang.org/cargo/getting-started/installation.html) and [mdBook](https://github.com/rust-lang/mdBook). + +After installing `cargo`, install `mdbook` with: +```bash +cargo install mdbook +``` + +## Building +To build a book, go into a book's directory and build: + +```bash +# This build Cuprate's architecture book. +cd architecture/ +mdbook build +``` + +The output will be in the `book` subdirectory (`architecture/book` for the above example). To open the book, you can open it in your web browser like so: +```bash +mdbook build --open +``` diff --git a/books/architecture/README.md b/books/architecture/README.md index 46409041..e4878432 100644 --- a/books/architecture/README.md +++ b/books/architecture/README.md @@ -1 +1,6 @@ -# TODO +## Cuprate's architecture (implementation) book +This book documents Cuprate's architecture and implementation. + +See: +- +- diff --git a/books/architecture/book.toml b/books/architecture/book.toml new file mode 100644 index 00000000..76724aa4 --- /dev/null +++ b/books/architecture/book.toml @@ -0,0 +1,19 @@ +[book] +authors = ["hinto-janai"] +language = "en" +multilingual = false +src = "src" +title = "Cuprate Architecture" +git-repository-url = "https://github.com/Cuprate/architecture-book" + +# TODO: fix after importing real files. +# +# [preprocessor.last-changed] +# command = "mdbook-last-changed" +# renderer = ["html"] +# +# [output.html] +# default-theme = "ayu" +# preferred-dark-theme = "ayu" +# git-repository-url = "https://github.com/hinto-janai/cuprate-architecture" +# additional-css = ["last-changed.css"] diff --git a/books/architecture/src/SUMMARY.md b/books/architecture/src/SUMMARY.md new file mode 100644 index 00000000..2b8615c9 --- /dev/null +++ b/books/architecture/src/SUMMARY.md @@ -0,0 +1,3 @@ +# Summary + +- [TODO](todo.md) diff --git a/books/architecture/src/todo.md b/books/architecture/src/todo.md new file mode 100644 index 00000000..46409041 --- /dev/null +++ b/books/architecture/src/todo.md @@ -0,0 +1 @@ +# TODO diff --git a/books/protocol/README.md b/books/protocol/README.md index 46409041..49c63b88 100644 --- a/books/protocol/README.md +++ b/books/protocol/README.md @@ -1 +1,6 @@ -# TODO +## Cuprate's protocol book +This book documents the Monero protocol. + +See: +- +-