Merge pull request #4405 from opsmill/pmc-20240920-install-docs

install docs cleanup

docs/docs/development/backend.mdx

@@ -13,7 +13,7 @@ In order start developing on Infrahub backend, it is recommended to have a decen
 
 To fetch Infrahub's code, we will use Git and we will use the `develop` branch (default).
 
-```bash
+```shell
 git clone --recursive git@github.com:opsmill/infrahub.git
 cd infrahub
 ```
@@ -22,7 +22,7 @@ cd infrahub
 
 Most of Infrahub and tools around it rely on some settings. These settings are in general set as environment variables, dealing with many of these can be hard to maintain and manage. We can use a tool such as [direnv](https://direnv.net/) to help. It allows to define environment variables (or pretty much anything bash can make sense of) in a file that will be interpreted when entering a given directory. Here is an example of a `.envrc` file providing development friendly setting values:
 
-```bash
+```shell
 export INFRAHUB_PRODUCTION=false
 export INFRAHUB_SECURITY_SECRET_KEY=super-secret
 export INFRAHUB_USERNAME=admin
@@ -48,32 +48,32 @@ Infrahub uses several external services to work:
 
 To run all these services, we will use Docker, but for local development some ports will need to be bound to local ones. To do so, a very basic Docker Compose override file is provided in the `development` directory, but it has a `tmp` extension which makes Compose ignore it by default. We will copy this file to a new one without the `tmp` extension. In a development environment, having only the services in Docker and Infrahub running on local Python is convenient to take advantage of the server auto-reload feature when making changes.
 
-```bash
+```shell
 cp development/docker-compose.dev-override.yml.tmp development/docker-compose.dev-override.yml
 ```
 
 Now we need to make sure we have a compatible version of Python that Infrahub can run on top of, Poetry to create virtual environment and Invoke to run commands. Invoke can be installed in many ways, but we recommend to use the `pipx` way to get it available user wide while without messing with the system Python. Assuming we have these utilities ready, we can run the following commands to build a proper Python environment:
 
-```bash
+```shell
 cd infrahub # or the directory of your choice
 poetry install
 ```
 
 Now it's time to bring the required services up, and for that we have demo commands:
 
-```bash
+```shell
 invoke dev.destroy dev.deps
 ```
 
 This will actually pass two commands, one to destroy any remains of a previous run and one to start services. So this will effectively bring up clean services without leftovers. We can see which services are running by using:
 
-```bash
+```shell
 poetry run invoke dev.status
 ```
 
 This should yield a Docker output like the following:
 
-```bash
+```shell
 NAME                       IMAGE                      COMMAND                  SERVICE         CREATED       STATUS                 PORTS
 infrahub-cache-1           redis:7.2                  "docker-entrypoint.s…"   cache           2 hours ago   Up 2 hours (healthy)   0.0.0.0:6379->6379/tcp
 infrahub-database-1        memgraph/memgraph:2.13.0   "/usr/lib/memgraph/m…"   database        2 hours ago   Up 2 hours (healthy)   0.0.0.0:7444->7444/tcp, 0.0.0.0:7474->7474/tcp, 0.0.0.0:7687->7687/tcp
@@ -86,7 +86,7 @@ When following a guide, like the [installation guide](/guides/installation.mdx),
 
 With the required services working and properly setup Python virtual environment we can now run the Infrahub test suite to make sure the code works as intended.
 
-```bash
+```shell
 INFRAHUB_LOG_LEVEL=CRITICAL pytest -v backend/tests/unit
 ```
 
@@ -96,7 +96,7 @@ The environment variable at the beginning of the command is useful to have a muc
 
 We can run the Infrahub server with the built-in command:
 
-```bash
+```shell
 infrahub server start --debug
 ```
 
@@ -111,14 +111,14 @@ For running the frontend, please refer to its [dedicated documentation section](
 
 For testing code changes, you may want to load a new schema from a YAML file. This can be performed in the development environment using:
 
-```bash
+```shell
 poetry run infrahubctl schema load ${PATH_TO_SCHEMA_FILE}
 ```
 
 ## Code format
 
 Formatting code in the backend relies on [Ruff](https://docs.astral.sh/ruff/) and [yamllint](https://yamllint.readthedocs.io/en/stable/). To ensure all files are as close as possible to the expected format, it is recommended to run the `format` command:
 
-```bash
+```shell
 poetry run invoke format
 ```

docs/docs/development/docs.mdx

@@ -18,7 +18,7 @@ The recommended way to run and build the docs locally is with Infrahub's suite o
 
 Once these requirements are met, you'll have access to the doc task list.
 
-```bash
+```shell
 invoke -l docs
 ```
 
@@ -195,7 +195,7 @@ await saveScreenshotForDocs(page, "my-screenshot-name");
 
 To update all documentation screenshots, run:
 
-```bash
+```shell
 cd frontend/app
 npm run test:e2e:screenshots
 ```
@@ -292,7 +292,7 @@ Feature: Explanation of feature
 When creating a code block or snippet with three backticks, make sure to include a language designation.
 <!-- markdownlint-disable -->
 ~~~md
-```bash
+```shell
 this is a shell script
 ```
 ~~~

docs/docs/development/frontend/getting-set-up.mdx

@@ -8,29 +8,29 @@ title: Getting set up
 
 Make sure [Infrahub Backend](../backend.mdx) is up and running. If not, in your terminal execute:
 
-```bash
+```shell
 invoke demo.destroy demo.build demo.start demo.load-infra-schema demo.load-infra-data
 ```
 
 :::
 
 Infrahub is built with React. Make sure you're running Node.js 20+ and NPM 9+, to verify do:
 
-```bash
+```shell
 node --version
 npm --version
 ```
 
 ## 1. Install dependencies
 
-```bash
+```shell
 cd frontend/app
 npm install
 ```
 
 ## 2. Start a local server
 
-```bash
+```shell
 npm start
 ```
 
@@ -40,7 +40,7 @@ To can access your local server at [http://localhost:8080/](http://localhost:808
 
 ### Unit tests
 
-```bash
+```shell
 npm run test
 
 # same with coverage
@@ -49,13 +49,13 @@ npm run test:coverage
 
 ### Integration tests
 
-```bash
+```shell
 npm run cypress:run:component
 ```
 
 ### E2E tests
 
-```bash
+```shell
 npm run test:e2e
 ```
 

docs/docs/development/frontend/readme.mdx

@@ -27,7 +27,7 @@ For testing, we rely on:
 
 To access Infrahub's codebase, use Git and switch to the `develop` branch to access the latest changes. All frontend code resides in `/frontend`.
 
-```bash
+```shell
 git clone --recursive git@github.com:opsmill/infrahub.git
 cd infrahub/frontend
 ```

docs/docs/development/frontend/testing-guidelines.mdx

@@ -30,7 +30,7 @@ E2E tests are located in `/frontend/app/tests/e2e`.
 
 [Playwright](https://playwright.dev/docs/codegen) can automatically generate tests as you perform actions in the browser, making it a quick way to start testing:
 
-```bash
+```shell
 npx playwright codegen
 ```
 
@@ -81,7 +81,7 @@ page.getByRole("button", { name: "Save" });
 
 2. Structure tests with steps for better readability:
 
-```bash
+```shell
 # headless mode
 npm run test:e2e
 
@@ -97,13 +97,13 @@ npm run test:e2e:ui
 
 ## Integration tests
 
-```bash
+```shell
 npm run cypress:run:component
 ```
 
 ## Unit tests
 
-```bash
+```shell
 npm run test
 
 # same with coverage

docs/docs/faq/faq.mdx

@@ -129,7 +129,7 @@ Please see the documentation on [integrations](../integrations) for more informa
 
 Infrahub collects anonymous usage metrics and sends them to OpsMill servers for analysis and improvement purposes. No personally identifiable information is collected. If you prefer to opt-out of telemetry collection, you can do so by setting the `INFRAHUB_TELEMETRY_OPTOUT` environment variable to `true`:
 
-```bash
+```shell
 export INFRAHUB_TELEMETRY_OPTOUT=true
 ```
 

docs/docs/guides/artifact.mdx

@@ -45,7 +45,7 @@ More details on the `.infrahub.yml` file format can be found in [.infrahub.yml t
 
 Commit the changes to the repository and push them to the Git server
 
-```bash
+```shell
 git add .
 git commit -m "add tags_config_file artifact definition"
 git push origin main

docs/docs/guides/check.mdx

@@ -25,7 +25,7 @@ As the first step we need to have some data in the database to actually query.
 Create three tags, called "color-red", "color-green", "blue", either using the frontend or by submitting three GraphQL mutations as per below (just swapping out the name of the color each time).
 Note that the "blue" tag is following a different naming scheme compared to the other tags. This is on purpose and is needed for the rest of the guide.
 
-```GraphQL
+```graphql
 mutation CreateTags {
   BuiltinTagCreate(
       data: {name: {value: "color-red"}, description: {value: "The red tag"}}
@@ -40,7 +40,7 @@ mutation CreateTags {
 
 The next step is to create a query that returns the data we just created. The rest of this guide assumes that the following query will return a response similar to the response below the query.
 
-```GraphQL
+```graphql
 query TagsQuery {
   BuiltinTag {
     edges {
@@ -102,7 +102,7 @@ Response to the tags query:
 
 Create a local directory on your computer.
 
-```bash
+```shell
 mkdir tags_check
 ```
 
@@ -207,7 +207,7 @@ Within the `tags_check` folder you should now have 3 files:
 
 Before we can test our transform we must add the files to a local Git repository.
 
-```bash
+```shell
 git init --initial-branch=main
 git add .
 git commit -m "First commit"
@@ -217,14 +217,14 @@ git commit -m "First commit"
 
 Using infrahubctl you can first verify that the `.infrahub.yml` file is formatted correctly by listing available checks.
 
-```bash title="❯ infrahubctl check --list"
+```shell title="❯ infrahubctl check --list"
 Python checks defined in repository: 1
 check_color_tags_name (tags_check.py::ColorTagsCheck) Target: -global-
 ```
 
 Run the check by specifying the name of the check as an argument.
 
-```bash title="❯ infrahubctl check check_color_tags_name"
+```shell title="❯ infrahubctl check check_color_tags_name"
 [09:23:25] INFO     HTTP Request: POST http://localhost:8000/graphql "HTTP/1.1 200 OK"
            ERROR    tags_check::ColorTagsCheck: FAILED
            ERROR      Invalid tag name: blue
@@ -352,7 +352,7 @@ We need to modify the GraphQL query with the `name` parameter. The GraphQL query
 
 Replace the contents of the `tags_check.gql` file with the following contents.
 
-```GraphQL
+```graphql
 query TagsQuery($name: String!) {
   BuiltinTag(name__value: $name) {
     edges {
@@ -371,7 +371,7 @@ query TagsQuery($name: String!) {
 
 ### 5. Test the `check_color_tags_name` check
 
-```bash title="❯ infrahubctl check check_color_tags_name"
+```shell title="❯ infrahubctl check check_color_tags_name"
 ``[11:50:43] INFO     HTTP Request: GET http://localhost:8000/api/schema/?branch=main "HTTP/1.1 200 OK"
            INFO     HTTP Request: POST http://localhost:8000/graphql/main "HTTP/1.1 200 OK"
            INFO     HTTP Request: POST http://localhost:8000/graphql/main "HTTP/1.1 200 OK"
@@ -493,15 +493,15 @@ We now have 2 targeted checks defined, each targeting its own set of tags, with
 
 Verify that we have 2 checks defined using the `infrahubctl` command.
 
-```bash title="❯ infrahubctl check --list"
+```shell title="❯ infrahubctl check --list"
 Python checks defined in repository: 2
 check_color_tags_name (tags_check.py::ColorTagsCheck) Target: ColorTags
 check_number_tags_name (tags_check.py::NumberTagsCheck) Target: NumberTags
 ```
 
 Check that the `check_color_tags_name` fails because of the tag `blue` not complying with the naming scheme:
 
-```bash title="❯ infrahubctl check check_color_tags_name"
+```shell title="❯ infrahubctl check check_color_tags_name"
 [14:04:50] INFO     HTTP Request: GET http://localhost:8000/api/schema/?branch=main "HTTP/1.1 200 OK
 [14:04:51] INFO     HTTP Request: POST http://localhost:8000/graphql/main "HTTP/1.1 200 OK"
            INFO     HTTP Request: POST http://localhost:8000/graphql/main "HTTP/1.1 200 OK"
@@ -518,7 +518,7 @@ Check that the `check_color_tags_name` fails because of the tag `blue` not compl
 
 Check that the `check_number_tags_name` succeeds:
 
-```bash title="❯ infrahubctl check check_number_tags_name"
+```shell title="❯ infrahubctl check check_number_tags_name"
 [14:09:32] INFO     HTTP Request: GET http://localhost:8000/api/schema/?branch=main "HTTP/1.1 200 OK"
            INFO     HTTP Request: POST http://localhost:8000/graphql/main "HTTP/1.1 200 OK"
            INFO     HTTP Request: POST http://localhost:8000/graphql/main "HTTP/1.1 200 OK"