sridhartigera / docs

Unified docs repository for Calico and Tigera

Calico & Tigera Docs

This is the full set of product docs for Calico & Tigera. It includes our Open Source (Project Calico) docs as well as our Enterprise and Cloud docs.

This website is built using Docusaurus 2, a modern static website generator.

Prerequisites

Either

• docker (to run the containerised version of the build)

Or

• Node.js v18.18.2+ (v18.18.2 recommended). Use the outstanding nvm tool to manage your node versions.
• yarn npm install -g yarn
• Fork and clone our docs repo https://github.com/tigera/docs

Local development

make start 

or

make start CONTAINERIZED=true

This command starts a local development server on http://localhost:3000. Most changes are reflected live without having to restart the server. This build is faster, but does not produce all the warnings and errors of a full build.

Full build and serve

make build
make serve

or

make build CONTAINERIZED=true
make serve CONTAINERIZED=true

This command generates static content into the build directory and can be served using any static content hosting service. This is a full build which is exactly what Netlify runs to build the site, therefore, you will get more warning and error output. If you are trying to reproduce an error on Netlify, this is a great place to start.

Building the site with unreleased docs versions

In production, we don't build or publish unreleased doc sets. If you'd like to preview changes to those versions locally, you can run the following commands:

make serve-next

make build-next
make serve

Viewing changes in preview builds

Each pull request against the main branch generates two preview builds. You can find links to these preview builds as comments from Netlify.

• Deploy preview. A full build with our production configuration.
• Deploy preview for calico-docs-preview-next. This builds the site based on the current state of our unversioned development directories:
  • calico/
  • calico-enteprise/
  • calico-cloud/

If you're making changes to an upcoming version of any of the products, review your changes in calico-docs-preview-next.

Viewing your changes locally for unreleased documentation

If you prefer to view changes to unreleased documentation locally, you must modify the docusuarus.config.js file. Add 'next' to the list for onlyIncludeVersions for the product docs you want to build.

      {
        id: 'calico',
        path: 'calico',
        routeBasePath: 'calico',
        editCurrentVersion: true,
        onlyIncludeVersions: ['next','3.27','3.26','3.25'], // 'next' is added to build the in-development docs  
        versions: {
          current: {
            label: 'Next',
            path: 'next',
            banner: 'unreleased',
          },
          3.28: {
            label: '3.28 (latest)',
            path: '3.28',
            banner: 'none'
          },
          3.27: {
            label: '3.27 (latest)',
            path: 'latest',
            banner: 'none',
          },

With this configuration, run yarn start or yarn build && yarn serve to see your changes.

Updating the Operator API docs

This repo includes functionality to automatically update the Operator API docs from the current version of Operator for each branch. The following Makefile targets will help you update the docs you want to update:

Automatically update all branches for all products:

make autogen

Automatically update all branches for a specific product:

make autogen_calico         # To update all Calico OSS releases
make autogen_enterprise     # To update all Calico Enterprise releases
make autogen_cloud          # To update all Calico Cloud releases

Detect and print a list of all of the makefile targets for each branch for all products. You can then run one of these targets to update the operator reference specifically for that branch.

# Get the list of operator reference update targets
❯ make show_current_branches
Calico branch targets:
* calico__operator_reference
* calico_versioned_docs/version-3.25__operator_reference
* calico_versioned_docs/version-3.26__operator_reference
* calico_versioned_docs/version-3.27__operator_reference

Calico enterprise branch targets:
* calico-enterprise__operator_reference
* calico-enterprise_versioned_docs/version-3.16__operator_reference
* calico-enterprise_versioned_docs/version-3.17__operator_reference
* calico-enterprise_versioned_docs/version-3.18__operator_reference
* calico-enterprise_versioned_docs/version-3.18-2__operator_reference
* calico-enterprise_versioned_docs/version-3.19-1__operator_reference

Calico cloud branch targets:
* calico-cloud__operator_reference
* calico-cloud_versioned_docs/version-19-1__operator_reference

# Trigger the operator reference update for Calico Enterprise v3.18
❯ make calico-enterprise_versioned_docs/version-3.18__operator_reference
...build output here...