Merge pull request #588 from loco-rs/improve-docs-with-snipdoc

improve docs with snipdoc

.github/workflows/docs.yml

@@ -0,0 +1,33 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+env:
+  RUST_TOOLCHAIN: stable
+  TOOLCHAIN_PROFILE: minimal
+
+jobs:
+  check:
+    name: Check
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+
+    steps:
+      - name: Checkout the code
+        uses: actions/checkout@v4
+      - uses: actions-rs/toolchain@v1
+        with:
+          profile: ${{ env.TOOLCHAIN_PROFILE }}
+          toolchain: ${{ env.RUST_TOOLCHAIN }}
+          override: true
+          components: rustfmt
+      - run: cargo install snipdoc        
+      - run: snipdoc check        
+
+

CONTRIBUTING.md

@@ -64,9 +64,19 @@ In case of cli changes we snapshot the binary commands. in case of changes run t
 LOCO_CI_MODE=true TRYCMD=overwrite cargo test
 ```
 
-## Running Docs website
-The documentation website based on [zola](https://www.getzola.org/), and you can see the docs [here](./docs-site/).
-then cd to `docs-site` and run `zola serve`
+## Docs
+
+The documentation consists of two main components:
+
++ The [loco.rs website](https://loco.rs) with its source code available [here](./docs-site/).
++ RustDocs.
+
+To reduce duplication in documentation and examples, we use [snipdoc](https://github.com/kaplanelad/snipdoc). As part of our CI process, we ensure that the documentation remains consistent.
+
+Updating the Documentation
++ Download [snipdoc](https://github.com/kaplanelad/snipdoc).
++ Create the snippet in the [yaml file](./snipdoc.yml) or inline the code.
++ Run `snipdoc run`.
 
 
 ## Open A Pull Request

README.md

@@ -1,103 +1,102 @@
+ <div align="center">
 
-![Loco.rs](https://github.com/loco-rs/loco/assets/83390/992d215a-3cd3-42ee-a1c7-de9fd25a5bac)
-[![Current Crates.io Version](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)
-[![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)
+   <img src="https://github.com/loco-rs/loco/assets/83390/992d215a-3cd3-42ee-a1c7-de9fd25a5bac"/>
 
-# Welcome to Loco!
+   <h1>Loco</h1>
 
-<a href="https://loco.rs">https://loco.rs</a>
+   <h3>
+   <!-- <snip id="description" inject_from="yaml"> -->
+🚂 Loco is Rust on Rails.
+<!--</snip> -->
+   </h3>
 
+   [![crate](https://img.shields.io/crates/v/loco-rs.svg)](https://crates.io/crates/loco-rs)
+   [![docs](https://docs.rs/loco-rs/badge.svg)](https://docs.rs/loco-rs)
+   [![Discord channel](https://img.shields.io/badge/discord-Join-us)](https://discord.gg/fTvyBzwKS8)
 
-Loco is "Rust on Rails".
+ </div>
 
-Loco is strongly inspired by Rails. If you know Rails and Rust, you'll feel at home. If you only know Rails and new to Rust, you'll find Loco refreshing. We do not assume you know Rails.
+ # Loco
 
+ #### Loco is strongly inspired by Rails. If you know Rails and Rust, you'll feel at home. If you only know Rails and new to Rust, you'll find Loco refreshing. We do not assume you know Rails.
 
-## Quick Start
-
+ ## Quick Start
+<!-- <snip id="quick-installation-command" inject_from="yaml"> -->
 ```sh
-$ cargo install loco-cli
+cargo install loco-cli
+cargo install sea-orm-cli # Only when DB is needed
 ```
+<!-- </snip> -->
 
-Now you can create your new app (choose "SaaS app").
+ Now you can create your new app (choose "`SaaS` app").
 
+<!-- <snip id="loco-cli-new-from-template" inject_from="yaml"> -->
 ```sh
-$ loco new
-❯ App name? [myapp]:
-❯ SaaS app (with DB and user auth)
-  Stateless service (minimal, no db)
+❯ loco new
+✔ ❯ App name? · myapp
+✔ ❯ What would you like to build? · SaaS app (with DB and user auth)
+
 🚂 Loco app generated successfully in:
 myapp
 ```
+<!-- </snip> -->
 
-To configure a database , please run a local postgres database with <code>loco:loco</code> and a db named <code>[insert app]_development</code>.
 
+To configure a database , please run a local postgres database with loco:loco and a db named [insert app]_development.
+<!-- <snip id="postgres-run-docker-command" inject_from="yaml"> -->
+```sh
+docker run -d -p 5432:5432 \
+  -e POSTGRES_USER=loco \
+  -e POSTGRES_DB=myapp_development \
+  -e POSTGRES_PASSWORD="loco" \
+  postgres:15.3-alpine
 ```
-$ docker run -d -p 5432:5432 -e POSTGRES_USER=loco -e POSTGRES_DB=myapp_development -e POSTGRES_PASSWORD="loco" postgres:15.3-alpine
-```
+<!-- </snip> -->
 
 
-Now `cd` into your `myapp` and start your app:
+ A more advanced set of `docker-compose.yml` and `Dockerfiles` that include Redis and the `mailtutan` mailer are available for [each starter on GitHub](https://github.com/loco-rs/loco/blob/master/starters/saas/.devcontainer/docker-compose.yml).
 
-```
-$ cd myapp
-$ cargo loco start
-Finished dev [unoptimized + debuginfo] target(s) in 21.63s
-    Running `target/debug/myapp start`
-
-    :
-    :
-    :
+ Now `cd` into your `myapp` and start your app:
 
-controller/app_routes.rs:203: [Middleware] Adding log trace id
+ <!-- <snip id="starting-the-server-command-with-output" inject_from="yaml"> -->
+```sh
+$ cargo loco start
 
                       ▄     ▀
-                                 ▀  ▄
+                                ▀  ▄
                   ▄       ▀     ▄  ▄ ▄▀
                                     ▄ ▀▄▄
                         ▄     ▀    ▀  ▀▄▀█▄
                                           ▀█▄
 ▄▄▄▄▄▄▄  ▄▄▄▄▄▄▄▄▄   ▄▄▄▄▄▄▄▄▄▄▄ ▄▄▄▄▄▄▄▄▄ ▀▀█
- ██████  █████   ███ █████   ███ █████   ███ ▀█
- ██████  █████   ███ █████   ▀▀▀ █████   ███ ▄█▄
- ██████  █████   ███ █████       █████   ███ ████▄
- ██████  █████   ███ █████   ▄▄▄ █████   ███ █████
- ██████  █████   ███  ████   ███ █████   ███ ████▀
-   ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀ ██▀
-       ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
-
-started on port 3000
+██████  █████   ███ █████   ███ █████   ███ ▀█
+██████  █████   ███ █████   ▀▀▀ █████   ███ ▄█▄
+██████  █████   ███ █████       █████   ███ ████▄
+██████  █████   ███ █████   ▄▄▄ █████   ███ █████
+██████  █████   ███  ████   ███ █████   ███ ████▀
+  ▀▀▀██▄ ▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀  ▀▀▀▀▀▀▀▀▀▀ ██▀
+      ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+                https://loco.rs
+
+listening on port 3000
 ```
+<!-- </snip> -->
 
 ## Project Status
-
-Loco is feature complete, but features are still being added rapidly.
-
-### What can you build?
-
-- Stateless APIs
-- Complete SaaS products with user authentication
-- Purpose-built services such as ML inference endpoints
-- Full stack projects with separate frontend project integrated with Loco
-- Hobby projects full-stack with backend and HTML frontend
-
-### What's being done now?
-
-- View [issues](https://github.com/loco-rs/loco/issues) for what we plan next and what we work on (you're welcome to submit PRs!)
-- View [CHANGELOG](https://github.com/loco-rs/loco/blob/master/CHANGELOG.md) for what we already added
++ Stateless APIs
++ Complete `SaaS` products with user authentication
++ Purpose-built services such as ML inference endpoints
++ Full stack projects with separate frontend project integrated with Loco
++ Hobby projects full-stack with backend and HTML frontend
 
 ## Powered by Loco
-
-* [SpectralOps](https://spectralops.io) - various services powered by Loco framework
-* [Nativish](https://nativi.sh) - app backend powered by Loco framework
-
-[open an issue to add yourself here](https://github.com/loco-rs/loco/issues)
-
++ [SpectralOps](https://spectralops.io) - various services powered by Loco
+  framework
++ [Nativish](https://nativi.sh) - app backend powered by Loco framework
 
 ## Contributors ✨
-
 Thanks goes to these wonderful people:
 
 <a href="https://github.com/loco-rs/loco/graphs/contributors">
   <img src="https://contrib.rocks/image?repo=loco-rs/loco" />
-</a>
+</a>

docs-site/content/blog/frontend-website.md

@@ -147,7 +147,6 @@ server:
 ```
 
 Now, run the Loco server again and you should see frontend app serving via Loco
-
 ```sh
 $ cargo loco start
 ```

docs-site/content/docs/getting-started/cli.md

@@ -16,18 +16,24 @@ flair =[]
 
 Create your starter app:
 
-```rust
-$ cargo install loco-cli
-$ loco new
-< follow the guide >
+<!-- <snip id="loco-cli-new-from-template" inject_from="yaml"> -->
+```sh
+❯ loco new
+✔ ❯ App name? · myapp
+✔ ❯ What would you like to build? · SaaS app (with DB and user auth)
+
+🚂 Loco app generated successfully in:
+myapp
 ```
+<!-- </snip> -->
 
 Now `cd` into your app, set up a convenience `rr` alias and try out the various commands:
 
+<!-- <snip id="help-command" inject_from="yaml"> -->
+```sh
+cargo loco --help
 ```
-$ cd myapp
-$ cargo loco --help
-```
+<!-- </snip> -->
 
 You can now drive your development through the CLI:
 
@@ -49,9 +55,11 @@ $ cargo test
 
 To run you app, run:
 
+<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+```sh
+cargo loco start
 ```
-$ cargo loco start
-```
+<!-- </snip> -->
 
 ## Background workers
 

docs-site/content/docs/getting-started/config.md

@@ -61,27 +61,23 @@ config/
 ```
 
 To run the application using the 'qa' environment, execute the following command:
-
-```
-$ LOCO_ENV=qa cargo loco start
+<!-- <snip id="starting-the-server-command-with-environment-env-var" inject_from="yaml"> -->
+```sh
+LOCO_ENV=qa cargo loco start
 ```
+<!-- </snip> -->
 
 ## Settings
 
-The configuration files contain knobs to set up your Loco app. You can also have your custom settings, with the `settings:` section.
-
-
-```yaml
-# in config/development.yaml
-# add the `settings:` section
-settings:
+The configuration files contain knobs to set up your Loco app. You can also have your custom settings, with the `settings:` section. in `config/development.yaml` add the `settings:` section
+<!-- <snip id="configuration-settings" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
+```yaml 
+ settings:
   allow_list:
     - google.com
-    - apple.com
-
-logger:
-  # ...
-```
+    - apple.com 
+ ```
+<!-- </snip> -->
 
 These setting will appear in `ctx.config.settings` as `serde_json::Value`. You can create your strongly typed settings by adding a struct: