docs: Wording changes and proper syntax highlighting

README.md

@@ -4,7 +4,7 @@ Codepod provides the interactive coding experience popularized by Jupyter, but
 with scalability and production-readiness. Users can still incrementally build
 up code by trying out a small code snippet each time. But they would not be
 overwhelmed by the great number of code snippets as the projects grow. Try
-it online at https://codepod.io !
+it online at [https://codepod.io](https://codepod.io) !
 
 ![screenshot](./screenshot-canvas.png)
 
@@ -19,7 +19,7 @@ along your adventure with Codepod.
 
 CodePod is open source under MIT license. Feel free to contribute! We can make
 it better together. You can contribute by opening an issue, discussion, or
-submit a pull request. Please use [Prettier](https://prettier.io/) (e.g., [its
+submitting a pull request. Do use [Prettier](https://prettier.io/) (e.g., [its
 VSCode
 plugin](https://marketplace.visualstudio.com/items?itemName=esbenp.prettier-vscode))
 to format your code before checking in.
@@ -30,12 +30,12 @@ The docker compose files are in `compose/dev` folder. The `dev` stack mounts the
 `src` folder, so that you can edit the files on your local computer, and let the
 node.js process inside the container do the compiling and hot-reloading.
 
-To install docker-compose, follow [this official instruction](https://docs.docker.com/compose/install/linux/).
+To install docker-compose, follow the official [Docker documentation](https://docs.docker.com/compose/install/linux/).
 
 First, create a `dev/.env` file with the following content (leave as is or change the value to
-whatever you want). You probably don't need the GOOGLE_CLIENT_ID is you don't need Google's OAuth.
+whatever you want). Leave the `GOOGLE_CLIENT_ID` empty if you do not need the OAuth provided by Google.
 
-```
+```properties
 POSTGRES_USER=myusername
 POSTGRES_PASSWORD=mypassword
 POSTGRES_DB=mydbname
@@ -45,26 +45,24 @@ GOOGLE_CLIENT_ID=<google oauth client id>
 
 Start the stack:
 
-```
+```bash
 cd dev
 docker compose up -d
 ```
 
-You need to initialized the database if this is the first time to start the stack. See below.
+You need to initialized the database first before starting the stack. See below.
 
-Wait a few minutes for packages installation and compilation. Once `ui` and
-`api` containers are ready listening on http ports, go to `http://localhost:80`
-to see the app.
+Wait a few minutes for the package installation and compilation. Once the `ui` and
+`api` containers are ready, go to `http://localhost:80` to see the app.
 
 - `http://localhost:80/graphql`: Apollo GraphQL explorer for the backend APIs
 - `http://prisma.127.0.0.1.sslip.io`: Prisma Studio for viewing and debugging the database.
 
 ## Initialize the database
 
-If this is your first time running it, the database is empty, and you need to
-initialize the database. To do that, open a shell into the API container and run:
+If this is your first time running it, you would need to initialize the database as it's empty. To do that, open a shell into the API container and run:
 
-```
+```bash
 npx prisma migrate dev
 ```
 
@@ -75,11 +73,16 @@ This command is also needed after the database schema is changed. The protocol i
   migration, e.g. [this
   migration](./api/prisma/migrations/20221206194247_add_google_login/migration.sql).
   The schema change along with this migration need to be checked in to git.
-- Another developer pull the change, then run `npx prisma migrate dev` (in the
-  api container's shell) to apply the schema change.
+- Another developer pulls the change, then running the `npx prisma migrate dev` (in the api container's shell) to apply the schema change.
 
 ## Auto-completion & Linting
 
-Although we develop using docker, we still want auto-complete and linting while
-coding. For that to work, you need to install the node packages locally, i.e.,
-run `yarn` in `api/`, `ui/`, etc.
+Although we developed this project using docker, we still want features like auto-completion and linting while coding. For that to work, you need to install the all the relevant node packages, i.e.
+
+```bash
+# api, proxy, runtime, ui
+cd ./api/
+
+# Run 'npm install' instead if you are using npm
+yarn
+```

api/README.md

@@ -1,9 +1,9 @@
 # CP Kernel
 
-This is a package designed for code sharing between codepod API and electron server.
+This is a package designed for code sharing between the codepod API and the electron server.
 
 To use the kernel:
-If you use `yarn`, you can run `yarn add link:/path/to/cpkernel`. However, this will not work with npm. For npm, you need to run `npm link` in cpkernel folder to globally register the package, and run `npm link cpkernel` to link. This won't reflect in package.json.
+If you use `yarn`, you can run `yarn add link:/path/to/cpkernel`. However, this will not work with npm. For `npm`, you need to run `npm link` in cpkernel folder to register the package globally, and run `npm link cpkernel` to link. This won't reflect in package.json.
 
 Thus the ideal setup should be to add cpkernel to package.json, but not to install it. Instead, run `npm link cpkernel` during development.
 
@@ -13,13 +13,13 @@ Thus the ideal setup should be to add cpkernel to package.json, but not to insta
 
 ## Spin up the container
 
-```
+```bash
 docker-compose up -d
 ```
 
-This will create postgreSQL, listening on http://localhost:5432. The username and password is stored in .env. The template is copied here:
+This will create postgreSQL, listening on [http://localhost:5432](http://localhost:5432). The username and password is stored in the `.env` file. The template is copied here:
 
-```
+```properties
 NEO4J_URI=bolt://localhost:7687
 NEO4J_USER=neo4j
 NEO4J_PASSWORD=codepod123
@@ -42,41 +42,41 @@ Need to run migrate for the first time if the DB is not initialized on a new ser
 
 migrate DB:
 
-```
+```bash
 npx prisma migrate dev --name init
 ```
 
 create another migration with just a different name:
 
-```
+```bash
 prisma migrate dev --name added_job_title
 ```
 
 generate client (the migrate will run this, so no need anymore. But do not
-forget to do this after schema change, otherwise you'll end up with debugging
+forget to do this after changing the schema, otherwise you'll end up with debugging
 strange errors):
 
-```
+```bash
 npx prisma generate
 ```
 
 The studio can be viewed at
 
-```
+```bash
 npx prisma studio
 ```
 
 When I mess up with the database and want to start from scratch:
 
-```
+```bash
 npx prisma db push --preview-feature
 ```
 
 ## Building node-pty
 
-Install nvm and node, yarn as usual. Running of `yarn` may fail (to build
-node-pty) due to missing development packages. On Ubuntu install:
+Install nvm and node, yarn as usual. Though running `yarn` may fail (to build
+node-pty) due to missing development packages. On Ubuntu, fixing it by running:
 
-```
+```bash
 sudo apt install -y make python build-essential
 ```

k8s/helm-chart/README.md

@@ -6,14 +6,16 @@
 
 We need to create one more namespace manually:
 
-    kubectl create ns codepod-staging
-    kubectl create ns codepod-staging-runtime
+```bash
+kubectl create ns codepod-staging
+kubectl create ns codepod-staging-runtime
+```
 
 ### (DEPRECATED) Apply the secrets
 
 Need the secrets:
 
-```
+```yaml
 apiVersion: v1
 kind: Secret
 type: Opaque
@@ -28,14 +30,16 @@ data:
 
 Note: the secrets must be base64 encoded with:
 
-    echo -n your-password | base64
+```bash
+echo -n your-password | base64
+```
 
 Need the -n there, otherwise there will be a space when this secret is used in
-env variables. Ref: https://github.com/kubernetes/kubernetes/issues/28086
+env variables. Ref: [https://github.com/kubernetes/kubernetes/issues/28086](https://github.com/kubernetes/kubernetes/issues/28086)
 
 Need to manually apply these secrets:
 
-```
+```bash
 kubectl apply -f secrets.yaml
 ```
 
@@ -52,57 +56,73 @@ See `../cert-manager`. Basically:
 3. define issuers (clusterwise)
 4. retrieve certs (into codepod-prod namespace)
 
-Ref: https://docs.technotim.live/posts/kube-traefik-cert-manager-le/#cert-manager
+Ref: [https://docs.technotim.live/posts/kube-traefik-cert-manager-le/#cert-manager](https://docs.technotim.live/posts/kube-traefik-cert-manager-le/#cert-manager)
 
 End result: the app-codepod-io-tls certificate.
 
 ## Install
 
 Install:
 
-    helm install codepod-staging . --namespace codepod-staging --create-namespace --values=./values.staging.yaml
+```bash
+helm install codepod-staging . --namespace codepod-staging --create-namespace --values=./values.staging.yaml
+```
 
 Upgrade:
 
-    helm upgrade codepod-staging . --namespace codepod-staging --values=./values.staging.yaml
+```bash
+helm upgrade codepod-staging . --namespace codepod-staging --values=./values.staging.yaml
+```
 
 Optionally initialize the DB (run in one api pod):
 
-    npx prisma migrate dev --name init
+```bash
+npx prisma migrate dev --name init
+```
 
 - TODO: automate this
 - TODO: restore from backup
 
 Uninstall:
 
-    helm uninstall codepod-staging
+```bash
+helm uninstall codepod-staging
+```
 
 Prod:
 
-    helm upgrade codepod-prod . --namespace codepod-prod --values=./values.prod.yaml
+```bash
+helm upgrade codepod-prod . --namespace codepod-prod --values=./values.prod.yaml
+```
 
 ## Helper scripts
 
 Alpha:
 
-    kubectl apply -f secrets.yaml -n codepod-alpha
-    helm install codepod-alpha . --namespace codepod-alpha --create-namespace --values=./values.alpha.yaml
+```bash
+kubectl apply -f secrets.yaml -n codepod-alpha
+helm install codepod-alpha . --namespace codepod-alpha --create-namespace --values=./values.alpha.yaml
 
-    helm upgrade codepod-alpha . --namespace codepod-alpha --values=./values.alpha.yaml
+helm upgrade codepod-alpha . --namespace codepod-alpha --values=./values.alpha.yaml
+```
 
 Rollback:
 
-    helm rollback -n codepod-alpha codepod-alpha
-    helm rollback -n codepod-alpha codepod-alpha 11
-    helm ls -n codepod-alpha
+```bash
+helm rollback -n codepod-alpha codepod-alpha
+helm rollback -n codepod-alpha codepod-alpha 11
+helm ls -n codepod-alpha
+```
 
 To access prisma:
 
-    kubectl port-forward prisma-deployment-5c9ccfc6b8-962vq 5555:5555 -n codepod-alpha
+```bash
+kubectl port-forward prisma-deployment-5c9ccfc6b8-962vq 5555:5555 -n codepod-alpha
+```
 
 ## Config maps and secrets
 
-```
+```yaml
 apiVersion: v1
 kind: Secret
 type: Opaque
@@ -114,7 +134,7 @@ data:
 
 ```
 
-```
+```yaml
 apiVersion: v1
 kind: ConfigMap
 metadata:

runtime/README.md

@@ -4,19 +4,19 @@ This folder contains the proxy server and runtime server.
 
 ## Development
 
-First, spin up a ipython Jupyter kernel:
+1. Spin up an ipython Jupyter kernel:
 
-```
-python3 -m ipykernel_launcher -f ./kernel/conn.json
-```
+	```bash
+	python3 -m ipykernel_launcher -f ./kernel/conn.json
+	```
 
-Second, spin up the websocket server:
+2. Spin up the websocket server:
 
-```
-yarn devws
-```
+	```bash
+	yarn devws
+	```
 
-Now, the socket server is running at http://localhost:4020. This URL is used in
+Now, the socket server is running at [http://localhost:4020](http://localhost:4020). This URL is used in
 the front-end runtime.js to connect to the runtime.
 
 ## (TODO) proxy server