Merge rust-bitcoin/www.rust-bitcoin.org#9: feat: cookbook v1

cee4953 feat: cookbook (Einherjar)

Pull request description:

  - [x] Convert `build.sh` to a GitHub Actions and closes #6.
  - [x] Automated CI in GitHub Actions that test all the code in the cookbook: `.github/workflows/test.yml`
  - [x] Automated scheduled CI in GitHub Actions that check all markdown files for broken links (we are adding a LOT of links to the `rust-bitcoin` docs): `.github/workflows/check-links.yml`
  - [x] Dependabot to update (weekly) `.github/dependabot.yml`:
    - [x] GitHub Actions
    - [x] Test dependencies, this is good once we release `rust-bitcoin` new versions dependabot will open a PR here to update
  - [x] `justfile` to easy run the build and test with `just`
  - [x] ~~This is how you receive data over P2P~~ moved to #10.
  - [x] ~~This is how you parse blocks and transactions~~ moved to #11.
  - [x] This is how you construct and sign transactions
    - [x] [TABConf 2023 segwit signing exercise](https://github.com/tcharding/workshop/tree/master/sign-segwit-v0)
    - [x] [TABConf 2023 taproot signing exercise](https://github.com/tcharding/workshop/tree/master/sign-taproot)

  ## Details

  I want this cookbook to be tested automatically on CI, so the code will always run.
  The only solution that worked for me was [this workaround](rust-lang/mdBook#706 (comment)) that is used in [The Rust Rand Book](https://github.com/rust-random/book).

ACKs for top commit:
  sanket1729:
    utACK [cee4953](cee4953). Go ahead
  tcharding:
    ACK cee4953

Tree-SHA512: 94a2349380b8dab0c913ab5665d64ae714a8afa56bef82fa47d6d03184db49472ba2b3580b4ac781be3e2356c684041ac33a15ee26aa24c284688d8e71548b22

.github/dependabot.yml

@@ -0,0 +1,13 @@
+# Set update schedule for GitHub Actions
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      # Check for updates to GitHub Actions every week
+      interval: "weekly"
+  - package-ecosystem: "cargo"
+    directory: "/cookbook/tests" # point this towards a Cargo.toml directory
+    schedule:
+      # Check for updates to Rust dependencies every week
+      interval: "weekly"

.github/workflows/check-links.yml

@@ -0,0 +1,25 @@
+name: Markdown Links Check
+# runs every monday at 9 am
+on:
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch: null
+
+jobs:
+  check-links:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        # checks all markdown files from /cookbook including all subfolders
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'
+          folder-path: 'cookbook/'
+      - uses: actions/checkout@v4
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        # checks all markdown files from root but ignores subfolders
+        with:
+          use-quiet-mode: 'yes'
+          use-verbose-mode: 'yes'
+          max-depth: 0

.github/workflows/gh-pages.yml

@@ -0,0 +1,44 @@
+# This needs the following setting:
+# Setttings > Actions > General > Workflow permissions
+# change to "Read and write permissions"
+name: github pages
+
+on:
+  push:
+    branches:
+      - master
+  workflow_dispatch: null
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          submodules: true # could be useful in the future
+          fetch-depth: 0   # we just need the latest commit
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+
+      - name: Build mdbook
+        working-directory: ./cookbook
+        run: mdbook build --dest-dir "../site/static/book"
+
+      - name: Setup Hugo
+        uses: peaceiris/actions-hugo@v2
+        with:
+          hugo-version: "latest"
+
+      - name: Build Hugo
+        working-directory: ./site
+        run: hugo --minify
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        if: github.ref == 'refs/heads/master'
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site/public

.github/workflows/test.yml

@@ -0,0 +1,28 @@
+name: Tests
+on:
+  push:
+    branches: [ master, '[0-9]+.[0-9]+.[0-9]+', '[0-9]+.[0-9]+.[0-9]+-[A-Za-z0-9]+' ]
+  pull_request:
+    branches: [ master, '[0-9]+.[0-9]+.[0-9]+', '[0-9]+.[0-9]+.[0-9]+-[A-Za-z0-9]+' ]
+# runs every monday at 9 am
+  schedule:
+    - cron: "0 9 * * 1"
+  workflow_dispatch: null
+
+jobs:
+  code-samples:
+    name: Test code samples
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install toolchain
+        uses: actions-rs/toolchain@v1
+        with:
+          profile: minimal
+          toolchain: stable
+      - name: Generate harness
+        working-directory: ./cookbook/tests
+        run: ./generate.sh
+      - name: Test code samples
+        working-directory: ./cookbook/tests
+        run: cargo test

.gitignore

@@ -6,4 +6,7 @@ site/.hugo_build.lock
 
 # mdbook build
 cookbook/book
+cookbook/tests/Cargo.lock
+cookbook/tests/target
+cookbook/tests/src
 site/static/book

README.md

@@ -7,3 +7,13 @@ Website for the rust-bitcoin ecosystem. The site is built using [hugo](https://g
 [nightfall](https://themes.gohugo.io/themes/hugo-theme-nightfall/) theme.
 
 Includes a cookbook built with [mdbook](https://rust-lang.github.io/mdBook/).
+
+## License
+
+This website is licensed under [CC0 1.0 Universal (CC0 1.0) Public Domain Dedication][cc].
+
+[![CC BY-SA 4.0][cc-image]][cc]
+
+[cc]: https://creativecommons.org/publicdomain/zero/1.0/
+[cc-image]: https://licensebuttons.net/l/by-sa/4.0/88x31.png
+[cc-shield]: https://img.shields.io/badge/License-CC0%201.0-lightgrey.svg

cookbook/README.md

@@ -1,9 +1,58 @@
-# Rust Bitcoin CookBook
+# Rust Bitcoin Cookbook
 
-Welcome to the Rust-Bitcoin documentation! This documentation is designed to provide readers with a
-comprehensive understanding of Rust-Bitcoin and its key features.
+[![CC0 1.0][cc-shield]][cc]
 
+Welcome to the `rust-bitcoin` cookbook!
+This cookbook is designed to provide readers with a
+comprehensive understanding of `rust-bitcoin` and its key features.
+Don't forget to check [`rust-bitcoin`'s documentation](https://docs.rs/bitcoin)
 
-## Build
+## How to contribute
 
-The book can be built with `mdbook`: https://rust-lang.github.io/mdBook/
+For the cookbook we use [`mdbook`](https://rust-lang.github.io/mdBook).
+Please check how to install it on your system.
+
+To build the cookbook locally, run:
+
+```bash
+mdbook build
+```
+
+If you want to preview the cookbook locally, run:
+
+```bash
+mdbook serve
+```
+
+### Testing the code snippets
+
+Since [`mdbook` does not support external crates](https://github.com/rust-lang/mdBook/issues/706),
+we use [a solution provided by `doc-comment`](https://github.com/rust-lang/mdBook/issues/706#issuecomment-1139423009)
+to test the code snippets in the cookbook.
+First, go to the `tests/` directory:
+
+```bash
+cd tests
+```
+
+Then, run the `generate.sh` to automatically generate all tests files:
+
+```bash
+./generate.sh
+```
+
+Finally run the tests:
+
+```bash
+cargo test
+```
+
+## License
+
+This website is licensed under [CC0 1.0 Universal (CC0 1.0) Public Domain Dedication][cc].
+
+[![CC BY-SA 4.0][cc-image]][cc]
+
+[cc]: https://creativecommons.org/publicdomain/zero/1.0/
+[cc-image]: https://licensebuttons.net/l/by-sa/4.0/88x31.png
+[cc-shield]: https://img.shields.io/badge/License-CC0%201.0-lightgrey.svg

cookbook/book.toml

@@ -1,6 +1,17 @@
 [book]
-authors = ["Harshil Jani"]
+authors = [
+    "Harshil Jani <harshiljani2002@gmail.com>",
+    "Tobin C. Harding<me@tobin.cc>",
+    "Einherjar <realeinherjar@proton.me>",
+]
 language = "en"
 multilingual = false
 src = "src"
 title = "Rust Bitcoin Cookbook"
+description = "A cookbook for Rust Bitcoin development"
+
+[rust]
+edition = "2021"
+
+[output.html.playground]
+runnable = false # playground is not runnable by default

cookbook/src/SUMMARY.md

@@ -1,5 +1,7 @@
 # Summary
 
-[Table of Contents](./table_of_contents.md)
-[About](./about.md)
-- [Chapter 1](./chapter_1.md)
+[Introduction](./intro.md)
+
+- [Constructing and Signing Transactions](tx.md)
+  - [SegWit V0](tx_segwit-v0.md)
+  - [Taproot](tx_taproot.md)

cookbook/src/intro.md

@@ -0,0 +1,46 @@
+# Rust Bitcoin
+
+[![CC0 1.0][cc-shield]][cc]
+
+[`rust-bitcoin`](https://github.com/rust-bitcoin/rust-bitcoin) is a library for working with Bitcoin in Rust.
+It contains Bitcoin network protocol and associated primitives.
+You can find more by reading the [documentation](https://docs.rs/bitcoin).
+
+To add `rust-bitcoin` to your project, run:
+
+```bash
+cargo add bitcoin
+```
+
+Additionally, you can add flags to enable features.
+Here's an example:
+
+```bash
+cargo add bitcoin --features=rand-std
+```
+
+This cookbook provides straightforward examples that showcase effective approaches
+for accomplishing typical Bitcoin-related programming tasks,
+and utilizing the Rust ecosystem's crates.
+
+The book covers various topics, including receiving data over P2P,
+parsing blocks and transactions,
+and constructing and signing transactions.
+
+## Table of Contents
+
+This book contains:
+
+1. [Constructing and Signing Transactions](tx.md)
+    1. [SegWit V0](tx_segwit-v0.md)
+    1. [Taproot](tx_taproot.md)
+
+## License
+
+This website is licensed under [CC0 1.0 Universal (CC0 1.0) Public Domain Dedication][cc].
+
+[![CC BY-SA 4.0][cc-image]][cc]
+
+[cc]: https://creativecommons.org/publicdomain/zero/1.0/
+[cc-image]: https://licensebuttons.net/l/by-sa/4.0/88x31.png
+[cc-shield]: https://img.shields.io/badge/License-CC0%201.0-lightgrey.svg

cookbook/src/tx.md

@@ -0,0 +1,6 @@
+# Constructing and Signing Transactions
+
+We provide the following examples:
+
+- [Constructing and Signing Transactions - SegWit V0](tx_segwit-v0.md)
+- [Constructing and Signing Transactions - Taproot](tx_taproot.md)