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

Enhance and standardize connector documentation #580

Open
slyons opened this issue Nov 1, 2024 · 0 comments
Open

Enhance and standardize connector documentation #580

slyons opened this issue Nov 1, 2024 · 0 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@slyons
Copy link
Contributor

slyons commented Nov 1, 2024

There should be a fixed set of sections and standards for the connector documentation.

The connector docs should follow the following layout:

# Title

* Brief description of the connector. Link to relevant external documentation
* Small spicepod sample

## Configuration
### `from`

<Explanation of the `from` field>

### `name`

Name of the dataset, used as the table name in Spice.

Example:
```yaml
datasets:
  - from: s3://s3-bucket-name/taxi_sample.csv
    name: cool_dataset
    params:
      file_format: csv
```

```sql
SELECT COUNT(*) FROM cool_dataset;
```

```shell
+----------+
| count(*) |
+----------+
| 6001215  |
+----------+
```

### `params`

A markdown table of the available parameters. Parameters can be split up into multiple tables for readability. Parameters that support secrets should link to the "Using secrets" section at the end of the page

## Examples

Each example should have a heading and optionally a very brief description. There should be as many examples as possible

## Using secrets

A section describing and linking to the Secrets page. Avoid using the `TabItem`s because they're hard to link to. If there's an example of a specific use case of using one of the secrets providers, include it in the Examples section. This section should look like so:

## Secrets

Spice supports three types of [secret stores](/components/secret-stores):

* [Environment variables](/components/secret-stores/env)
* [Kubernetes Secret Store](/components/secret-stores/kubernetes)
* [Keyring Secret Store](/components/secret-stores/keyring)

Explore the different options to manage sensitive data securely.
@slyons slyons added the documentation Improvements or additions to documentation label Nov 1, 2024
@slyons slyons self-assigned this Nov 1, 2024
slyons added a commit that referenced this issue Nov 15, 2024
* Standardizing ABFS docs

* Making document more concise and consistent with #580

* Adding `file_format` to params section

* Updating secrets section

* Rephrasing secrets section

* Update spiceaidocs/docs/components/data-connectors/abfs.md

Co-authored-by: Phillip LeBlanc <[email protected]>

* Update spiceaidocs/docs/components/data-connectors/abfs.md

Co-authored-by: Phillip LeBlanc <[email protected]>

* Update spiceaidocs/docs/components/data-connectors/abfs.md

Co-authored-by: Phillip LeBlanc <[email protected]>

* Update spiceaidocs/docs/components/data-connectors/abfs.md

Co-authored-by: Phillip LeBlanc <[email protected]>

* Updating ABFS docs with suggestions

* Re-adding `hive_partitioning_enabled` parameter

* Clarifying `disable_tagging`

---------

Co-authored-by: Phillip LeBlanc <[email protected]>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation
Projects
None yet
Development

No branches or pull requests

1 participant