diff --git a/.github/workflows/docs.yaml b/.github/workflows/docs.yaml index 9b9a36e37..125f1f315 100644 --- a/.github/workflows/docs.yaml +++ b/.github/workflows/docs.yaml @@ -10,6 +10,10 @@ concurrency: group: ${{ github.workflow }}-${{ github.ref }} cancel-in-progress: true +env: + CARGO_TERM_COLOR: always + CARGO_NET_GIT_FETCH_WITH_CLI: "true" + jobs: build: name: Build the documentation @@ -18,6 +22,14 @@ jobs: - name: Checkout the code uses: actions/checkout@v3 + - name: Install Rust toolchain + run: | + rustup toolchain install nightly + rustup default nightly + + - name: Setup Rust cache + uses: Swatinem/rust-cache@v2 + - name: Setup mdBook uses: peaceiris/actions-mdbook@v1.2.0 with: @@ -26,6 +38,12 @@ jobs: - name: Build the documentation run: mdbook build + - name: Build rustdoc + run: cargo doc -Zrustdoc-map --workspace --lib --no-deps + + - name: Move the Rust documentation within the mdBook + run: mv target/doc target/book/rustdoc + - name: Upload GitHub Pages artifacts uses: actions/upload-pages-artifact@v1.0.7 with: diff --git a/docs/development/architecture.md b/docs/development/architecture.md index f15b31203..691c881f4 100644 --- a/docs/development/architecture.md +++ b/docs/development/architecture.md @@ -10,17 +10,31 @@ The whole repository is a [Cargo Workspace](https://doc.rust-lang.org/book/ch14- This includes: - `mas-cli`: Command line utility, main entry point - - `mas-config`: Configuration parsing and loading - - `mas-data-model`: Models of objects that live in the database, regardless of the storage backend - - `mas-email`: High-level email sending abstraction - - `mas-handlers`: Main HTTP application logic - - `mas-iana`: Auto-generated enums from IANA registries - - `mas-iana-codegen`: Code generator for the `mas-iana` crate - - `mas-jose`: JWT/JWS/JWE/JWK abstraction - - `mas-static-files`: Frontend static files (CSS/JS). Includes some frontend tooling - - `mas-storage`: Interactions with the database - - `mas-tasks`: Asynchronous task runner and scheduler - - `oauth2-types`: Useful structures and types to deal with OAuth 2.0/OpenID Connect endpoints. This might end up published as a standalone library as it can be useful in other contexts. + - [`mas-config`][mas-config]: Configuration parsing and loading + - [`mas-data-model`][mas-data-model]: Models of objects that live in the database, regardless of the storage backend + - [`mas-email`][mas-email]: High-level email sending abstraction + - [`mas-handlers`][mas-handlers]: Main HTTP application logic + - [`mas-iana`][mas-iana]: Auto-generated enums from IANA registries + - [`mas-iana-codegen`][mas-iana-codegen]: Code generator for the `mas-iana` crate + - [`mas-jose`][mas-jose]: JWT/JWS/JWE/JWK abstraction + - [`mas-static-files`][mas-static-files]: Frontend static files (CSS/JS). Includes some frontend tooling + - [`mas-storage`][mas-storage]: Abstraction of the storage backends + - [`mas-storage-pg`][mas-storage-pg]: Storage backend implementation for a PostgreSQL database + - [`mas-tasks`][mas-tasks]: Asynchronous task runner and scheduler + - [`oauth2-types`][oauth2-types]: Useful structures and types to deal with OAuth 2.0/OpenID Connect endpoints. This might end up published as a standalone library as it can be useful in other contexts. + +[mas-config]: ../rustdoc/mas_config/index.html +[mas-data-model]: ../rustdoc/mas_data_model/index.html +[mas-email]: ../rustdoc/mas_email/index.html +[mas-handlers]: ../rustdoc/mas_handlers/index.html +[mas-iana]: ../rustdoc/mas_iana/index.html +[mas-iana-codegen]: ../rustdoc/mas_iana_codegen/index.html +[mas-jose]: ../rustdoc/mas_jose/index.html +[mas-static-files]: ../rustdoc/mas_static_files/index.html +[mas-storage]: ../rustdoc/mas_storage/index.html +[mas-storage-pg]: ../rustdoc/mas_storage/index.html +[mas-tasks]: ../rustdoc/mas_tasks/index.html +[oauth2-types]: ../rustdoc/oauth2_types/index.html ## Important crates diff --git a/docs/development/database.md b/docs/development/database.md index 80c6aef21..5ffe8a5a8 100644 --- a/docs/development/database.md +++ b/docs/development/database.md @@ -5,18 +5,22 @@ It provides async database operations with connection pooling, migrations suppor ## Writing database interactions -All database interactions are done through repositoriy traits. Each repository trait usually manages one type of data, defined in the `mas-data-model` crate. +All database interactions are done through repositoriy traits. Each repository trait usually manages one type of data, defined in the [`mas-data-model`][mas-data-model] crate. Defining a new data type and associated repository looks like this: - - Define new structs in `mas-data-model` crate - - Define the repository trait in `mas-storage` crate - - Make that repository trait available via the `RepositoryAccess` trait in `mas-storage` crate - - Setup the database schema by writing a migration file in `mas-storage-pg` crate - - Implement the new repository trait in `mas-storage-pg` crate - - Write tests for the PostgreSQL implementation in `mas-storage-pg` crate + - Define new structs in [`mas-data-model`][mas-data-model] crate + - Define the repository trait in [`mas-storage`][mas-storage] crate + - Make that repository trait available via the `RepositoryAccess` trait in [`mas-storage`][mas-storage] crate + - Setup the database schema by writing a migration file in [`mas-storage-pg`][mas-storage-pg] crate + - Implement the new repository trait in [`mas-storage-pg`][mas-storage-pg] crate + - Write tests for the PostgreSQL implementation in [`mas-storage-pg`][mas-storage-pg] crate -Some of those steps are documented in more details in the `mas-storage` and `mas-storage-pg` crates. +Some of those steps are documented in more details in the [`mas-storage`][mas-storage] and [`mas-storage-pg`][mas-storage-pg] crates. + +[mas-data-model]: ../rustdoc/mas_data_model/index.html +[mas-storage]: ../rustdoc/mas_storage/index.html +[mas-storage-pg]: ../rustdoc/mas_storage_pg/index.html ## Compile-time check of queries