Sur 02112024 docs #4834
Sur 02112024 docs #4834
Conversation
github-actions
bot
added
the
type/documentation
|
Cloudflare pages - https://sur-02112024-docs.infrahub.pages.dev/ |
| ```yaml | ||
| --- | ||
| version: '1.0' | ||
| nodes: |
There was a problem hiding this comment.
Maybe add the generics section as well
|
|
||
| The recommended way to manage and load a schema is to create a schema file in YAML format. With a schema file it's possible to: | ||
|
|
||
| - Define new nodes |
There was a problem hiding this comment.
| - Define new nodes | |
| - Define new nodes | |
| - Define new generics |
|
|
||
| ::: | ||
|
|
||
| ## Load a schema file |
There was a problem hiding this comment.
Maybe here we could guide people in the choice, when to use git integration vs infrahubctl, pros and cons.
For instance I added that paragraph in the schema library:
There are several ways to [load a schema in Infrahub](https://docs.infrahub.app/guides/import-schema):
Quick View: To take a quick look at a schema, you can use Infrahub CTL. Follow [this guide](https://docs.infrahub.app/infrahubctl) to install Infrahub CTL.
Controlled Integration: For a more organized and unified approach to loading schemas, you can connect a Git repository. Follow [this guide](https://docs.infrahub.app/guides/repository) to connect a Git repository.
| --- | ||
| schemas: | ||
| - schemas/demo_edge_fabric.yml | ||
| ``` |
There was a problem hiding this comment.
Maybe we can remove the following note below, it's redondant and not really related to the section load schema
docs/docs/infrahubctl.mdx
Outdated
| @@ -32,10 +32,12 @@ The `infrahubctl` command line utility is installed as a part of the [Infrahub S | |||
| | `INFRAHUB_API_TOKEN` | `06438eb2-8019-4776-878c-0941b1f1d1ec` | | |||
| | `INFRAHUB_DEFAULT_BRANCH` | main | | |||
|
|
|||
| > You can also provide the location of a configuration file via the environment variable `INFRAHUBCTL_CONFIG`. | |||
| You can obtain the `INFRAHUB_API_TOKEN` from the web GUI by navigating to 'Account Settings' under your profile and selecting 'Tokens'. You can also manage the tokens via GraphQL queries. You can find more information on how to do that [here](/guides/managing-api-tokens). | |||
There was a problem hiding this comment.
I'd just say "don't have a token yet? you can find more information on how to manage API token in this guide". So if one day we change that part of the product we can change only the directly related documentation
There was a problem hiding this comment.
Good point, I will change it.
There was a problem hiding this comment.
I have a feeling this file becomes a hodgepodge of things:
- It's a guide that explains how to load a schema
- It's a topic that explains what the schema is
- It's a reference that explains what the format of a schema file is
Here we line out how docs should be organized. I think we should split up the multiple aspects of this file into their proper sections, taken into account that some parts might already exist (like the schema reference and creating a schema guide)
https://docs.infrahub.app/development/docs#organizing-new-pages
| There are several ways to [load a new schema](/guides/import-schema). | ||
| ## Schema file | ||
|
|
||
| The recommended way to manage and load a schema is to create a schema file in YAML format. With a schema file it's possible to: |
There was a problem hiding this comment.
It's not necessarily the recommended way. It's just a way of doing it together with the repository method.
Arguably, in a production environment, you might want to have the schema in an external repository and let Infrahub import the changes from it.
infrahubctl schema load is great when you are developing a schema or trying to test something, or when you want to make one of changes, which might be required during some migrations.
There was a problem hiding this comment.
@wvandeun @BaptisteGi - Currently, under the Guides section, we have a 'Creating a Schema' page that covers a lot, including how to import the schema file. Then we have the next page, 'Schema File', which also covers how to import a schema file. That's why I thought it would be good to move the contents of that page under the 'Schema' topics. I didn't change anything except for adding 'How to generate the token'.
infrahubctlpage