documentation/README.md

# H2O LLM Studio Documentation

- The LLM Studio documentation is built using [Makersaurus](https://github.com/h2oai/makersaurus/pkgs/npm/makersaurus) which is a very thin wrapper around Facebook's Docusaurus.
- The documentation is displayed at {{ https://docs.h2o.ai/h2o-llm-studio/ }}

To view, edit, and cut a version of the documentation, the following is required:

- Node.js version 16.14+ (you can check your version by running `node -v`). Use nvm to manage multiple Node versions installed on a single machine.

- To install Node.js and npm with nvm in Mac or Ubuntu, run: `curl -o-
https://raw.githubusercontent.com/creationix/nvm/v0.33.0/install.sh | bash` and `nvm install node`

- Makersaurus (the H2O themed documentation site) is hosted on H2O's Github npm registry. npm must authenticate to the registry before you can download Makersaurus. Follow the 3 steps below to authenticate the npm package.

 If you have already installed `@h2oai/ui-kit` or any other private `@h2oai`-prefixed npm package you can skip this step.

 **Step 1:** Create a "classic" [personal access token](https://github.com/settings/tokens) (PAT) on Github. Note that you only need to enable the `read:packages` scope for this token. 

 **Step 2:** Add the PAT to your `~/.npmrc` file. Create this file if it doesn't exist yet. 
 ```
 @h2oai:registry=https://npm.pkg.github.com/
 //npm.pkg.github.com/:_authToken=YOUR-GENERATED-TOKEN
 ```
 **Step 3:** Verify that it worked by running the following command:
 ```
 npm whoami --registry=https://npm.pkg.github.com
 ```
 If this command returns your username, you can proceed to the next step. If you get an error, you are not yet authenticated. You might find the [Github registry docs](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry#authenticating-with-a-personal-access-token) helpful for debugging.

### Documentation structure


```
├── documentation
│ ├── docs
│ ├── tmp
│ ├── makersaurus.config.js
│ ├── sidebars.js
│ ├── package.json
│ ├── package-lock.json
```

- `documentation/docs`: Contains Markdown documentation files to edit the next documentation version.
Customize the order of the docs sidebar in `sidebars.js`
- `documentation/tmp`: Temporary files generated by Makersaurus. Do not edit these files.
- `documentation/makersaurus.config.js`: Makersaurus [config file](https://h2oai.github.io/makersaurus/api/config)
- `documentation/sidebars.js`: Sidebar configuration file
- `documentation/package.json`: npm configuration file
- `documentation/package-lock.json`: Generated by npm. Do not edit this file.


### Edit locally

To setup the local `env` to view and edit the next or past documentation versions ([first, ensure you install
Node.js](#requirements)):

1. Enter the documentation folder

`cd documentation`

2. Install dependencies

`npm install`

3. Start Makersaurus

`npm start`

- **Next documentation version**: To view your edits for the next documentation version, navigate to the provided URL.
Then, select **Next** on the **Versions** dropdown menu.
- **Debug**
- If you don't see anything after clicking **Next**, run the following command and try again:
`make setup-doc`
- Ensure that the following variable is set to `true` in the `makersaurus.config.js` file (located at `docs`):
`includeCurrentVersion`
- **Past documentation versions**: To view your edits for past documentation versions (located at
`docs/versioned_docs/`), navigate to the provided URL (for example, `http://localhost:3000/h2o-llm-studio/`). 
Then, select a *version* (for example, v0.2.0) on the **Versions** dropdown menu.

### Cut a version

To cut a new version after making specific changes at `documentation/docs` to align with the next version of the application, consider the following instructions:

1. Before a new version of the documentation is released, and right before we cut a version (`make version-doc`), change the following variable located in the `makersaurus.config.js` file to `false`: `includeCurrentVersion`
2. Run: `make version-doc` (for example, `make version-doc DOC_VERSION=v0.3.0`)
3. After the previous steps are executed and all generated files are pushed to the main branch, trigger the following
script in GitHub actions: `deploy-to-github-pages.yml`
4. After publishing the new documentation version, change the following variable located in the
`makersaurus.config.js` file to `true`: `includeCurrentVersion`
- This ensures the next doc version to edit will be visible while editing locally


## More information

Use the [Makersaurus docs](https://h2oai.github.io/makersaurus/) to learn more about how to edit docs, deploy the site, set up versioning and more.