ci: add doc.yml (#203)

* ci: add `doc.yml`

* update `{CONTRIBUTING,README}.md`

* readme: formatting

.github/workflows/doc.yml

@@ -0,0 +1,74 @@
+# This builds `cargo doc` and uploads it to the repo's GitHub Pages.
+
+name: Doc
+
+on:
+  push:
+    branches: [ "main" ] # Only deploy if `main` changes.
+  workflow_dispatch:
+
+env:
+  # Show colored output in CI.
+  CARGO_TERM_COLOR: always
+  # Fail on documentation warnings, generate an index page.
+  RUSTDOCFLAGS: '-D warnings --cfg docsrs --show-type-layout --enable-index-page -Zunstable-options'
+
+jobs:
+  # Build documentation.
+  build:
+    # FIXME: how to build and merge Windows + macOS docs
+    # with Linux's? Similar to the OS toggle on docs.rs.
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v4
+      with:
+        submodules: recursive
+
+    - name: Install Rust
+      uses: dtolnay/rust-toolchain@master
+      with:
+        # Nightly required for some `cargo doc` settings.
+        toolchain: nightly
+
+    - name: Cache
+      uses: actions/cache@v4
+      with:
+        # Don't cache actual doc files, just build files.
+        # This is so that removed crates don't show up.
+        path: target/debug
+        key: doc
+
+    # Packages other than `Boost` used by `Monero` are listed here.
+    # https://github.com/monero-project/monero/blob/c444a7e002036e834bfb4c68f04a121ce1af5825/.github/workflows/build.yml#L71
+
+    - name: Install dependencies (Linux)
+      run: sudo apt install -y libboost-dev
+
+    - name: Documentation
+      run: cargo +nightly doc --workspace --all-features
+
+    - name: Upload documentation
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: target/doc/
+
+  # Deployment job.
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    needs: build
+
+    # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

CONTRIBUTING.md

@@ -216,9 +216,9 @@ The description of pull requests should generally follow the template laid out i
 If your pull request is long and/or has sections that need clarifying, consider leaving a review on your own PR with comments explaining the changes.
 
 ## 5. Documentation
-Cuprate's crates (libraries) have inline documentation.
+Cuprate's crates (libraries) have inline documentation, they are published from the `main` branch at https://doc.cuprate.org.
 
-These can be built and viewed using the `cargo` tool. For example, to build and view a specific crate's documentation, run the following command at the repository's root:
+Documentation can be built and viewed using the `cargo` tool. For example, to build and view a specific crate's documentation, run the following command at the repository's root:
 ```bash
 cargo doc --open --package $CRATE
 ```

README.md

@@ -49,7 +49,7 @@ Cuprate maintains various documentation books:
 | [Monero's protocol book](https://monero-book.cuprate.org)       | Documents the Monero protocol                              |
 | [Cuprate's user book](https://user.cuprate.org)                 | Practical user-guide for using `cuprated`                  |
 
-For crate (library) documentation, see the `Documentation` section in [`CONTRIBUTING.md`](CONTRIBUTING.md).
+For crate (library) documentation, see: https://doc.cuprate.org. This site holds documentation for Cuprate's crates and all dependencies. All Cuprate crates start with `cuprate_`, for example: [`cuprate_database`](https://doc.cuprate.org/cuprate_database).
 
 ## Contributing