Skip to content

Commit

Permalink
Updated contributing md docs to fix locally running error on setup (#708
Browse files Browse the repository at this point in the history
)
  • Loading branch information
brianshen3 authored Oct 10, 2024
1 parent 59f9150 commit fdc43c5
Showing 1 changed file with 28 additions and 24 deletions.
52 changes: 28 additions & 24 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,34 @@ errors can be caught before committing code.
uv tool run pre-commit install
```

### Install insiders requirements

To build the documentation with "insider" features, run the [`setup_insiders.sh`](docs/setup_insiders.sh) script:

```
./docs/setup_insiders.sh
```

Note that this script requires an SSH key in your environment with access to the [kolenaIO](https://github.com/kolenaIO)
organization. Additionally, this script modifies the `pyproject.toml` to reference the "insider" versions of the mkdocs
projects. Please take care to avoid merging these updates, as it will prevent contributors without insiders access from
running `kolena`.

After running `setup_insiders.sh`, add `--config-file mkdocs.insiders.yml` to the `serve` and `build` invocations below
to build documentation with all "insider" features enabled.

### Images to load

Images used in documentation are stored in [`docs/assets/images`](docs/assets/images) and tracked with
[Git LFS](https://git-lfs.com/). All images in this directory are automatically tracked as LFS assets. Ensure that you
have LFS installed in your environment and run the following command:

```shell
git lfs install
```

Once lfs is installed, you will need to reclone the kolena repo because git lfs is needed to load images.

## Documentation

The documentation for `kolena`, hosted at [docs.kolena.com](https://docs.kolena.com/), is built out of this repo using
Expand Down Expand Up @@ -47,30 +75,6 @@ Kolena sponsors the [mkdocs-material](https://squidfunk.github.io/mkdocs-materia
preserve the capability to build documentation without access to these private "insider" repos, the docs dependencies
declared in [`pyproject.toml`](pyproject.toml) reference the publicly available package sources.

To build the documentation with "insider" features, run the [`setup_insiders.sh`](docs/setup_insiders.sh) script:

```
./docs/setup_insiders.sh
```

Note that this script requires an SSH key in your environment with access to the [kolenaIO](https://github.com/kolenaIO)
organization. Additionally, this script modifies the `pyproject.toml` to reference the "insider" versions of the mkdocs
projects. Please take care to avoid merging these updates, as it will prevent contributors without insiders access from
running `kolena`.

After running `setup_insiders.sh`, add `--config-file mkdocs.insiders.yml` to the `serve` and `build` invocations above
to build documentation with all "insider" features enabled.

### Images

Images used in documentation are stored in [`docs/assets/images`](docs/assets/images) and tracked with
[Git LFS](https://git-lfs.com/). All images in this directory are automatically tracked as LFS assets. Ensure that you
have LFS installed in your environment and run the following command:

```shell
git lfs install
```

### Links

Use relative paths, e.g. `../path-to-file.md`, to link to other pages within the documentation. Relative links that
Expand Down

0 comments on commit fdc43c5

Please sign in to comment.