Documentation

Overview

The documentation is written in MDX (opens in a new tab) and built with Nextra (opens in a new tab). Inside the docs/ directory, you can run the following commands:

# install the dependencies required to build the documentation
bun install
 
# start the development server
bun run dev
 
# build the production version of the documentation
bun run build

When building the documentation, static HTML files are generated in the out/ directory. You can deploy these files to any static hosting provider, such as Netlify (opens in a new tab) or Cloudflare Pages (opens in a new tab).

Automatic API Reference Syncing

Part of the documentation is not written by hand but is automatically generated from the source code. This part can be found in the API reference section. Running python docs/scripts/sync.py will update the respective files using the local source code. This includes:

• Copying the contents of the README.md file to docs/pages/index.mdx
• Generate a JSON Schema for each JSON file the codebase interacts with (configuration, etc.), and save it to docs/components/schemas/
• Copy the contents of config/config.template.json to the blocks inside docs/pages/file-interfaces/configuration.mdx and docs/pages/api-reference/configuration.mdx

Before releasing a version, please run the script docs/scripts/sync.py to sync the API reference. There is a pytest (tests/repository/test_api_reference_sync.py) that fails if the API reference is not up-to-date.

How to Host Versioned Documentation

The interfaces of your codebase and the schema of the files interacting with it (configuration, state, message archive) will most likely change over time. And since not all of your systems will run the latest software version, or you might want to roll back to a previous version, it is nice to have documentation of old versions accessible.

The interfaces should not change between patch versions (e.g., 1.0.0 to 1.0.1 or 0.1.5 to 0.1.6), that is why there should be one documentation per minor version (e.g., 0.1, 0.2, 1.0, 1.1, ...). This template includes a GitHub Action that will check out a branch named docs-vX.Y for every tag you push to GitHub. When you push the tags v0.1.0, then v0.1.1, then v0.1.2 and so on, the action will keep the respective docs-v0.1 branch up to date.

You can deploy multiple branches by using "Branch Deploys" on Netlify (opens in a new tab) or "Preview Deployments" on Cloudflare Pages (opens in a new tab).

The dropdown in the documentation's navigation bar is controlled in the file docs/pages/_meta.json:

{
  "Versions": {
    "title": "Versions",
    "type": "menu",
    "items": {
      "latest": {
        "title": "Latest",
        "href": "https://ivy-docs.pages.dev/"
      },
      "v0.2": {
        "title": "v0.2",
        "href": "https://docs-v0-2.ivy-docs.pages.dev/"
      },
      "v0.1": {
        "title": "v0.1",
        "href": "https://docs-v0-1.ivy-docs.pages.dev/"
      }
    }
  }
}