Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

install docs cleanup #4405

Merged
merged 3 commits into from
Sep 20, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 11 additions & 11 deletions docs/docs/development/backend.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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
Expand All @@ -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
Expand All @@ -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
```

Expand All @@ -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
```

Expand All @@ -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
```
6 changes: 3 additions & 3 deletions docs/docs/development/docs.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down Expand Up @@ -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
```
Expand Down Expand Up @@ -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
```
~~~
Expand Down
14 changes: 7 additions & 7 deletions docs/docs/development/frontend/getting-set-up.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand All @@ -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
Expand All @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/development/frontend/readme.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand Down
8 changes: 4 additions & 4 deletions docs/docs/development/frontend/testing-guidelines.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down Expand Up @@ -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

Expand All @@ -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
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/faq/faq.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
```

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/guides/artifact.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
22 changes: 11 additions & 11 deletions docs/docs/guides/check.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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"}}
Expand All @@ -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 {
Expand Down Expand Up @@ -102,7 +102,7 @@ Response to the tags query:

Create a local directory on your computer.

```bash
```shell
mkdir tags_check
```

Expand Down Expand Up @@ -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"
Expand All @@ -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
Expand Down Expand Up @@ -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 {
Expand All @@ -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"
Expand Down Expand Up @@ -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"
Expand All @@ -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"
Expand Down
Loading
Loading