File size: 4,766 Bytes
07423df |
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 |
# 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.
|