Merge pull request #596 from loco-rs/continue-with-docs-improvments

docs

.github/workflows/docs.yml

@@ -27,7 +27,9 @@ jobs:
           toolchain: ${{ env.RUST_TOOLCHAIN }}
           override: true
           components: rustfmt
-      - run: cargo install snipdoc        
+      - run: cargo install snipdoc --features exec
       - run: snipdoc check        
+        env:
+          SNIPDOC_SKIP_EXEC_COMMANDS: true
 
 

README.md

@@ -21,7 +21,7 @@
  #### 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
-<!-- <snip id="quick-installation-command" inject_from="yaml"> -->
+<!-- <snip id="quick-installation-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo install loco-cli
 cargo install sea-orm-cli # Only when DB is needed
@@ -30,7 +30,7 @@ cargo install sea-orm-cli # Only when DB is needed
 
  Now you can create your new app (choose "`SaaS` app").
 
-<!-- <snip id="loco-cli-new-from-template" inject_from="yaml"> -->
+<!-- <snip id="loco-cli-new-from-template" inject_from="yaml" template="sh"> -->
 ```sh
 ❯ loco new
 ✔ ❯ App name? · myapp
@@ -44,21 +44,19 @@ myapp
 
 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
-```
 <!-- </snip> -->
 
 
  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).
 
  Now `cd` into your `myapp` and start your app:
 
- <!-- <snip id="starting-the-server-command-with-output" inject_from="yaml"> -->
+ <!-- <snip id="starting-the-server-command-with-output" inject_from="yaml" template="sh"> -->
 ```sh
 $ cargo loco start
 

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

@@ -16,7 +16,7 @@ flair =[]
 
 Create your starter app:
 
-<!-- <snip id="loco-cli-new-from-template" inject_from="yaml"> -->
+<!-- <snip id="loco-cli-new-from-template" inject_from="yaml" template="sh"> -->
 ```sh
 ❯ loco new
 ✔ ❯ App name? · myapp
@@ -29,12 +29,37 @@ myapp
 
 Now `cd` into your app, set up a convenience `rr` alias and try out the various commands:
 
-<!-- <snip id="help-command" inject_from="yaml"> -->
+<!-- <snip id="help-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco --help
 ```
 <!-- </snip> -->
 
+<!-- <snip id="exec-help-command" inject_from="yaml" action="exec" template="sh"> -->
+```sh
+The one-person framework for Rust
+
+Usage: blo-cli [OPTIONS] <COMMAND>
+
+Commands:
+  start     Start an app
+  db        Perform DB operations
+  routes    Describe all application endpoints
+  task      Run a custom task
+  generate  code generation creates a set of files and code templates based on a predefined set of rules
+  doctor    Validate and diagnose configurations
+  version   Display the app version
+  help      Print this message or the help of the given subcommand(s)
+
+Options:
+  -e, --environment <ENVIRONMENT>  Specify the environment [default: development]
+  -h, --help                       Print help
+  -V, --version                    Print version
+
+```
+<!-- </snip> -->
+
+
 You can now drive your development through the CLI:
 
 ```
@@ -55,7 +80,7 @@ $ cargo test
 
 To run you app, run:
 
-<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco start
 ```

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

@@ -61,7 +61,7 @@ config/
 ```
 
 To run the application using the 'qa' environment, execute the following command:
-<!-- <snip id="starting-the-server-command-with-environment-env-var" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command-with-environment-env-var" inject_from="yaml" template="sh"> -->
 ```sh
 LOCO_ENV=qa cargo loco start
 ```
@@ -70,13 +70,13 @@ LOCO_ENV=qa cargo loco start
 ## 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:
+<!-- <snip id="configuration-settings" inject_from="code" template="yaml"> -->
+```yaml
+settings:
   allow_list:
     - google.com
-    - apple.com 
- ```
+    - 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:

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

@@ -17,7 +17,7 @@ Deployment is super simple in Loco, and this is why this guide is super short. A
 
 To deploy, build your production binary for your relevant server architecture:
 
-<!-- <snip id="build-command" inject_from="yaml"> -->
+<!-- <snip id="build-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo build --release
 ```
@@ -35,9 +35,9 @@ There are a few configuration sections that are important to review and set acco
 
 - Logger:
 
-<!-- <snip id="configuration-logger" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
-```yaml 
- # Application logging configuration
+<!-- <snip id="configuration-logger" inject_from="code" template="yaml"> -->
+```yaml
+# Application logging configuration
 logger:
   # Enable or disable logging.
   enable: true
@@ -49,28 +49,28 @@ logger:
   format: compact
   # By default the logger has filtering only logs that came from your code or logs that came from `loco` framework. to see all third party libraries
   # Uncomment the line below to override to see all third party libraries you can enable this config and override the logger filters.
-  # override_filter: trace 
- ```
+  # override_filter: trace
+```
 <!-- </snip>-->
 
 
 - Server:
-<!-- <snip id="configuration-server" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
-```yaml 
- server:
+<!-- <snip id="configuration-server" inject_from="code" template="yaml"> -->
+```yaml
+server:
   # Port on which the server will listen. the server binding is 0.0.0.0:{PORT}
   port: {{get_env(name="NODE_PORT", default=3000)}}
   # The UI hostname or IP address that mailers will point to.
   host: http://localhost
-  # Out of the box middleware configuration. to disable middleware you can changed the `enable` field to `false` of comment the middleware block 
- ```
+  # Out of the box middleware configuration. to disable middleware you can changed the `enable` field to `false` of comment the middleware block
+```
 <!-- </snip>-->
 
 
 - Database:
-<!-- <snip id="configuration-database" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
-```yaml 
- database:
+<!-- <snip id="configuration-database" inject_from="code" template="yaml"> -->
+```yaml
+database:
   # Database connection URI
   uri: {{get_env(name="DATABASE_URL", default="postgres://loco:loco@localhost:5432/loco_app")}}
   # When enabled, the sql query will be logged.
@@ -88,61 +88,61 @@ logger:
   # Truncate database when application loaded. This is a dangerous operation, make sure that you using this flag only on dev environments or test mode
   dangerously_truncate: false
   # Recreating schema when application loaded.  This is a dangerous operation, make sure that you using this flag only on dev environments or test mode
-  dangerously_recreate: false 
- ```
+  dangerously_recreate: false
+```
 <!-- </snip>-->
 
 
 - Mailer:
-<!-- <snip id="configuration-mailer" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
-```yaml 
- mailer:
+<!-- <snip id="configuration-mailer" inject_from="code" template="yaml"> -->
+```yaml
+mailer:
   # SMTP mailer configuration.
   smtp:
     # Enable/Disable smtp mailer.
-    enable: true
+    enable: true    
     # SMTP server host. e.x localhost, smtp.gmail.com
-    host: localhost
+    host: {{get_env(name="MAILER_HOST", default="localhost") }}
     # SMTP server port
     port: 1025
     # Use secure connection (SSL/TLS).
     secure: false
     # auth:
     #   user:
-    #   password: 
- ```
+    #   password:
+```
 <!-- </snip>-->
 
 - Queue:
-<!-- <snip id="configuration-queue" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
-```yaml 
- queue:
+<!-- <snip id="configuration-queue" inject_from="code" template="yaml"> -->
+```yaml
+queue:
   # Redis connection URI
   uri: {{get_env(name="REDIS_URL", default="redis://127.0.0.1")}}
   # Dangerously flush all data in Redis on startup. dangerous operation, make sure that you using this flag only on dev environments or test mode
-  dangerously_flush: false 
- ```
+  dangerously_flush: false
+```
 <!-- </snip>-->
 
 - JWT secret:
-<!-- <snip id="configuration-auth" inject_from="code" template="```yaml \n {snippet} \n ```"> -->
-```yaml 
- auth:
+<!-- <snip id="configuration-auth" inject_from="code" template="yaml"> -->
+```yaml
+auth:
   # JWT authentication
   jwt:
     # Secret key for token generation and verification
     secret: PqRwLF2rhHe8J22oBeHy
     # Token expiration time in seconds
-    expiration: 604800 # 7 days 
- ```
+    expiration: 604800 # 7 days
+```
 <!-- </snip>-->
 
 
 ## Generate
 
 Loco offers a deployment template enabling the creation of a deployment infrastructure.
 
-<!-- <snip id="generate-deployment-command" inject_from="yaml"> -->
+<!-- <snip id="generate-deployment-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco generate deployment
 ? ❯ Choose your deployment ›

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

@@ -43,7 +43,7 @@ You can follow this guide for a step-by-step "bottom up" learning, or you can ju
 
 ### Installing
 
-<!-- <snip id="quick-installation-command" inject_from="yaml"> -->
+<!-- <snip id="quick-installation-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo install loco-cli
 cargo install sea-orm-cli # Only when DB is needed
@@ -55,7 +55,7 @@ cargo install sea-orm-cli # Only when DB is needed
 
 Now you can create your new app (choose "SaaS app" for built-in authentication).
 
-<!-- <snip id="loco-cli-new-from-template" inject_from="yaml"> -->
+<!-- <snip id="loco-cli-new-from-template" inject_from="yaml" template="sh"> -->
 ```sh
 ❯ loco new
 ✔ ❯ App name? · myapp
@@ -84,7 +84,7 @@ To configure a database, please run a local postgres database with <code>loco:lo
 
 This docker command start up postgresql database server.
 
-<!-- <snip id="postgres-run-docker-command" inject_from="yaml"> -->
+<!-- <snip id="postgres-run-docker-command" inject_from="yaml" template="sh"> -->
 ```sh
 docker run -d -p 5432:5432 \
   -e POSTGRES_USER=loco \
@@ -102,7 +102,7 @@ docker run -p 6379:6379 -d redis redis-server
 
 Use doctor command to check the needed resources:
 
-<!-- <snip id="doctor-command" inject_from="yaml"> -->
+<!-- <snip id="doctor-command" inject_from="yaml template="sh"> -->
 ```sh
 $ cargo loco doctor
     Finished dev [unoptimized + debuginfo] target(s) in 0.32s
@@ -138,7 +138,7 @@ Let's get some responses quickly. For this, we need to start up the server.
 
 ### Starting the server
 
-<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco start
 ```
@@ -202,7 +202,7 @@ pub fn routes() -> Routes {
 
 Start the server:
 
-<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco start
 ```
@@ -275,7 +275,7 @@ impl Hooks for App {
 
 That's it. Kill the server and bring it up again:
 
-<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco start
 ```
@@ -524,7 +524,7 @@ pub fn routes() -> Routes {
 
 Now, start the app:
 
-<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco start
 ```
@@ -631,7 +631,7 @@ The order of the extractors is important, as changing the order of them can lead
 
 You can now test that it works, start the app:
 
-<!-- <snip id="starting-the-server-command" inject_from="yaml"> -->
+<!-- <snip id="starting-the-server-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo loco start
 ```

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

@@ -15,7 +15,7 @@ flair =[]
 
 Simplify your project setup with Loco's predefined boilerplates, designed to make your development journey smoother. To get started, install our CLI and choose the template that suits your needs.
 
-<!-- <snip id="quick-installation-command" inject_from="yaml"> -->
+<!-- <snip id="quick-installation-command" inject_from="yaml" template="sh"> -->
 ```sh
 cargo install loco-cli
 cargo install sea-orm-cli # Only when DB is needed
@@ -24,7 +24,7 @@ cargo install sea-orm-cli # Only when DB is needed
 
 Create a starter:
 
-<!-- <snip id="loco-cli-new-from-template" inject_from="yaml"> -->
+<!-- <snip id="loco-cli-new-from-template" inject_from="yaml" template="sh"> -->
 ```sh
 ❯ loco new
 ✔ ❯ App name? · myapp