docs: add myst parser

scylladb · Dec 6, 2023 · bf035f0 · bf035f0
1 parent f70eb27
commit bf035f0
Show file tree

Hide file tree

Showing 9 changed files with 68 additions and 70 deletions.
diff --git a/docs/build-with-go.md b/docs/build-with-go.md
@@ -1,7 +1,6 @@
-Build an IoT App with Go
-------------------------
+# Build an IoT App with Go
 
-### Introduction
+## Introduction
 
 In this section, we will walk you through the CarePet commands and explain the code behind them.
 
@@ -11,7 +10,7 @@ As explained in [Getting Started with CarePet](/getting-started.md), the project
 - Server (/cmd/server) - REST API service for tracking the pets’ health state.
 
 
-### Migrate
+## Migrate
 
 The `/migrate` command creates the keyspace and tables that will be used by the collar and server services.
 
@@ -75,7 +74,7 @@ func migrateKeyspace() {
 
 As the name suggests, the `printKeyspaceMetadata` function will then print the metadata related to the `carepet` keyspace and confirm that the tables were properly created.
 
-### Sensor
+## Sensor
 
 The sensor service simulates the collar's activity. The service uses the `pet struct` and its functions defined in `sensor/pet.go` to create a new `pet` along with an `owner` and `sensorType` then saves it to the database.
 
@@ -106,7 +105,7 @@ func main() {
 }
 ```
 
-### Server
+## Server
 
 The server service is a REST API for tracking the pets’ health state. The service allows users to query the database via http.
 
@@ -173,7 +172,7 @@ Line 25 queries the `owner` table then saves the result in the owner object or t
 
 Line 32 returns a FindOwnerByIDOK object with code status 200 and the owner's information.
 
-### Resources
+## Resources
 
 * [ScyllaDB Go driver on Github](https://github.com/scylladb/gocql)
 * [Go and ScyllaDB on ScyllaDB University](https://university.scylladb.com/courses/the-mutant-monitoring-system-training-course/lessons/golang-and-scylla-part-1/)

diff --git a/docs/build-with-java.md b/docs/build-with-java.md
@@ -1,6 +1,6 @@
-## Build an IoT App with Java
+# Build an IoT App with Java
 
-### Architecture
+## Architecture
 
 In this section, we will walk you through the CarePet commands and explain the code behind them.
 The project is structured as follows:
@@ -9,7 +9,7 @@ The project is structured as follows:
 -   Collar (`com.carepet.Sensor`) - Generates pet health data and pushes it into the storage.
 -   Web app (`com.carepet.server.App`) - REST API service for tracking pets' health state.
 
-### Migrate
+## Migrate
 
 The `./bin/migrate.sh --hosts $NODE1 --datacenter datacenter1` command executes the main function in the `Migrate` class located `Migrate.java`. The function creates the keyspace and tables used by the collar and server services.
 
@@ -111,7 +111,7 @@ AND read_repair_chance = 0.0
 AND speculative_retry = '99.0PERCENTILE';
 ```
 
-### Sensor
+## Sensor
 
 The sensor service simulates the collar's activity. You can use the following command to run the sensor service:
 
@@ -215,7 +215,7 @@ private void run() {
 }
 ```
 
-### Server
+## Server
 
 The server service is a REST API for tracking the pets’ health state. The service allows you to query the database via HTTP.
 
@@ -262,7 +262,7 @@ int current = now.getHour();
 
 ```
 
-### Resources
+## Resources
 
 * [Scylla Java driver documentation](https://java-driver.docs.scylladb.com/stable/)
 * [ScyllaDB Java driver on Github](https://github.com/scylladb/java-driver/)

diff --git a/docs/build-with-javascript.md b/docs/build-with-javascript.md
@@ -1,7 +1,6 @@
-Build an IoT App with JavaScript
-------------------------
+# Build an IoT App with JavaScript
 
-### Architecture
+## Architecture
 
 In this section, we will walk you through the CarePet commands and explain the code behind them.
 The project is structured as follows:
@@ -12,7 +11,7 @@ The project is structured as follows:
 - collar (`npm run sensor`) - Generates pet health data and pushes it into the storage.
 - web app (`npm run dev`) - REST API service for tracking pets' health state.
 
-### Code Structure and Implementation
+## Code Structure and Implementation
 
 The code package structure is as follows:
 
@@ -29,7 +28,7 @@ The code package structure is as follows:
 | /handler     | REST API handlers                   |
 | /model       | application models and ORM metadata |
 
-### Quick Start
+## Quick Start
 
 Prerequisites:
 
@@ -49,7 +48,7 @@ Make sure to install all NodeJS dependencies with:
 
     $ npm install
 
-### Use ScyllaDB on your local machine
+## Use ScyllaDB on your local machine
 
 To run a local ScyllaDB cluster consisting of three nodes with
 the help of `docker` and `docker-compose` execute:
@@ -63,9 +62,9 @@ Execute the following nodetool command:
 
     $ docker exec -it carepet-scylla1 nodetool status
 
-### Migrate
+## Migrate
 
-#### Run ScyllaDB on your local machine
+### Run ScyllaDB on your local machine
 
 Once all the nodes are in UN - Up Normal status, run the commands below.
 
@@ -87,7 +86,7 @@ You can check the database structure with:
 docker exec -it carepet-scylla1 cqlsh
 ```
 
-#### Using Scylla Cloud
+### Using Scylla Cloud
 
 If you are using Scylla Cloud, use the the following command to run the `migrate` service:
 
@@ -97,7 +96,7 @@ npm run migrate -- --hosts [NODE-IP] --username [USERNAME] --password[PASSWORD]
 
 Replace the NODE-IP, USERNAME, and PASSWORD with the information provided in your cluster on https://cloud.scylladb.com.
 
-### Output
+## Output
 
 Expected output:
 ```
@@ -164,7 +163,7 @@ CREATE TABLE carepet.pet (
 
 #. Run `exit` to exit the cqlsh.
 
-#### migrate/index.js
+### migrate/index.js
 
 The above commands execute the main function in the `cmd/migrate/index.js`. The function creates the keyspace and tables that you need to run the collar and server services.
 
@@ -289,17 +288,17 @@ CREATE TABLE carepet.pet (
     AND speculative_retry = '99.0PERCENTILE';
 ```
 
-### Sensor
+## Sensor
 
 The sensor service simulates the collar's activity and periodically saves data to the database. Use the below commands to run the sensor service:
 
-#### Using ScyllaDB on your local machine
+### Using ScyllaDB on your local machine
 ```
 NODE1=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' carepet-scylla1)
 npm run sensor -- --hosts $NODE1 --measure 5s --buffer-interval 1m
 ```
 
-#### Using Scylla Cloud
+### Using Scylla Cloud
 ```
 npm run sensor -- --hosts [NODE-IP] --username [USERNAME] --password [PASSWORD] --measure 5s --buffer-interval 1m
 ```
@@ -430,19 +429,19 @@ async function runSensorData(client, { bufferInterval, measure }, sensors) {
 }
 ```
 
-### Server
+## Server
 
 The server service is a REST API for tracking the pets’ health state. The service allows you to query the database via HTTP.
 
 Run the following commands to start the server:
 
-#### Using ScyllaDB on your local machine
+### Using ScyllaDB on your local machine
 ```
 NODE1=$(docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' carepet-scylla1)
 npm run dev -- --hosts $NODE1
 ```
 
-#### Using Scylla Cloud
+### Using Scylla Cloud
 ```
 npm run dev -- --hosts [NODE-IP] --username [USERNAME] --password [PASSWORD]
 ```
@@ -477,7 +476,7 @@ async function main() {
 }
 ```
 
-### Using the Application 
+## Using the Application 
 
 Open a different terminal to send an HTTP request from the CLI:
 
@@ -561,7 +560,7 @@ Expected output:
 
 `[0,0,0,0,0,0,0,0,0,0,0,0,0,0,42.55736]`
 
-### Resources
+## Resources
 
 * [Getting Started with ScyllaDB Cloud Using Node.js](https://www.scylladb.com/2022/03/14/getting-started-with-scylladb-cloud-using-node-js-part-1/)
 * [ScyllaDB University: Coding with Node.js](https://university.scylladb.com/courses/using-scylla-drivers/lessons/scylla-and-node-js/)

diff --git a/docs/build-with-python.md b/docs/build-with-python.md
@@ -1,6 +1,6 @@
-## Build an IoT App with Python
+# Build an IoT App with Python
 
-### Architecture
+## Architecture
 
 This section will walk through and explain the code for the different commands.
 As explained in the Getting Started page, the project is structured as follow:
@@ -9,7 +9,7 @@ As explained in the Getting Started page, the project is structured as follow:
 * Sensor (`python src/sensor.py`) - generates random IoT data and inserts it into ScyllaDB
 * API (`python src/api.py`) - REST API service to fetch data from ScyllaDB
 
-### Clone repository and install dependencies
+## Clone repository and install dependencies
 Clone the repository and open the root directory of the project:
 ```bash
 git clone https://github.com/scylladb/care-pet
@@ -27,7 +27,7 @@ Install all Python dependencies:
 pip install -r requirements.txt
 ```
 
-### Start Docker containers (skip this if you use Scylla Cloud)
+## Start Docker containers (skip this if you use Scylla Cloud)
 Spin up a local ScyllaDB cluster with three nodes using `docker` and `docker-compose`:
 ```bash
 docker-compose up -d
@@ -62,7 +62,7 @@ docker inspect carepet-scylla1
 ...
 ```
 
-### Connect to ScyllaDB and create the database schema
+## Connect to ScyllaDB and create the database schema
 To connect to your ScyllaDB storage within the container, you need to know the
 IP address of one of the running nodes.
 This is how you can get the IP address of the first node running in the container:
@@ -133,7 +133,7 @@ cqlsh:carepet> exit;
 
 At this point you have ScyllaDB running with the correct keyspace and tables.
 
-### Generate and ingest IoT data
+## Generate and ingest IoT data
 Start ingesting IoT data (it's suggested to do this in a new separate terminal
 because this process runs indefinitely). Make sure you're still in the virtual
 environment:
@@ -168,7 +168,7 @@ python src/sensor.py -h $NODE1 --measure 3 --buffer-interval 30
 
 You can run multiple ingestion processes in parallel if you wish.
 
-### Set up and test REST API
+## Set up and test REST API
 In a new terminal, start running the API server (make sure that `port 8000` is free):
 ```bash
 source env/bin/activate
@@ -249,7 +249,7 @@ curl http://127.0.0.1:8000/api/pet/44f1624e-07c2-4971-85a5-85b9ad1ff142/sensors
 [{"pet_id":"44f1624e-07c2-4971-85a5-85b9ad1ff142","sensor_id":"4bb1d214-712b-453b-b53a-ac5d4df4a1f8","type":"T"},{"pet_id":"44f1624e-07c2-4971-85a5-85b9ad1ff142","sensor_id":"e81915d6-1155-45e4-9174-c58e4cb8cecf","type":"L"}]
 ```
 
-### Resources
+## Resources
 
 * [ScyllaDB Python driver documentation](https://python-driver.docs.scylladb.com/stable/)
 * [ScyllaDB Python driver on Github](https://github.com/scylladb/python-driver/)

diff --git a/docs/build-with-rust.md b/docs/build-with-rust.md
@@ -1,6 +1,6 @@
-## Build an IoT App with Rust
+# Build an IoT App with Rust
 
-### Architecture
+## Architecture
 
 This section will walk through and explain the code for the different commands.
 As explained in the Getting Started page, the project is structured as follow:
@@ -9,7 +9,7 @@ As explained in the Getting Started page, the project is structured as follow:
 -   collar (`/bin/sensor/main.rs`) - generates a pet health data and pushes it into the storage
 -   web app (`/main.rs`) - REST API service for tracking pets health state
 
-### Migrate
+## Migrate
 
 Start by creating a local ScyllaDB cluster consisting of 3 nodes:
 
@@ -148,7 +148,7 @@ CREATE TABLE carepet.pet (
     AND speculative_retry = '99.0PERCENTILE';
 ```
 
-### Sensor
+## Sensor
 
 The sensor service simulates the collar's activity and periodically saves data to the database. Use the below commands to run the sensor service:
 
@@ -265,7 +265,7 @@ async fn run_sensor_data(cfg: &App, sess: &Session, sensors: Vec<Sensor>) -> Res
 }
 ```
 
-### Server
+## Server
 
 The server service is a REST API for tracking the pets’ health state. The service was built using [Rocket](https://rocket.rs) and allows users to query the database via HTTP.
 
@@ -353,7 +353,7 @@ The GET request on URL `/sensor/<id>/values?<from>&<to>` triggers `find_sensor_d
 
 `find_sensor_data_by_sensor_id_and_time_range` takes `session`, `id`, `from` and `to` as params. The function runs a `SELECT` query then returns `rows`.
 
-#### Retrieving informations from API
+## Retrieving informations from API
 
 To test out the API in your terminal, use the following command to retrieve informations of a specific pet owner: 
 
@@ -429,7 +429,7 @@ and you should receive a response similar to this:
 ```
 
 
-### Resources
+## Resources
 
 * [ScyllaDB Rust driver documentation](https://rust-driver.docs.scylladb.com/stable/)
 * [ScyllaDB Rust code examples](https://github.com/scylladb/scylla-rust-driver/tree/main/examples)

diff --git a/docs/conf.py b/docs/conf.py
@@ -27,11 +27,9 @@
     "sphinx_scylladb_theme",
     "sphinx_multiversion",
     "sphinx_sitemap",
-    "recommonmark",
-    "sphinx_markdown_tables"
+    "myst_parser"
 ]
 
-
 # The suffix(es) of source filenames.
 source_suffix = [".rst", ".md"]
 
@@ -101,6 +99,9 @@
 # They are copied to the output’s _static directory.
 html_static_path = ["_static"]
 
+# -- Options for myst parser ----------------------------------------
+myst_enable_extensions = ["colon_fence"]
+
 # -- Options for not found extension -------------------------------------------
 
 # Template used to render the 404.html generated by this extension.