documentation/README.md

H2O LLM Studio Documentation

• The LLM Studio documentation is built using 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 (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 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
• 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):

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 to learn more about how to edit docs, deploy the site, set up versioning and more.