How to use Krane Docs?

Krane Docs is the central place where all technical documentation about Krane should live.

Most of the documentation is contained in the krane-docusaurus repository. However, technical docs from other repositories can be included with git submodules. Currently, Management Dashboard documentation is included through a submodule.

Add another repo to the docs

External docs are added as a new navbar item with their own side bar. This is how the configuration for the management dashboard in docusaurus.config.ts looks like:

docusaurus.config.js

themeConfig: {
    // Replace with your project's social card
    image: 'img/orikami-logo.svg',
    navbar: {
      title: 'Krane Docs',
      logo: {
        alt: 'Orikami Logo',
        src: 'img/orikami-logo.svg',
      },
      items: [
        {
          type: 'docSidebar',
          sidebarId: 'kraneSidebar',
          position: 'left',
          label: 'Krane',
        },
        {
          type: 'docSidebar',
          sidebarId: 'managementDashboardSidebar',
          position: 'left',
          label: 'Management Dashboard',
        },
      ],
    },
    ...
}

and sidebars.ts

sidebars.ts

const sidebars: SidebarsConfig = {
  kraneSidebar: [{type: 'autogenerated', dirName: 'krane'}],
  managementDashboardSidebar: [{type: 'autogenerated', dirName: 'management-dashboard/docs'}],

To add a new repo first add the repo as a submodule to a sub-directory under the the docs directory.

git add submodule add git@github.com:orikami-nl/krane-gateway.git docs/gateway

We are only interested in the docs of the remote and not all other code. To get rid of the rest of the repo we can use git sparse-checkout.

git sparse-checkout set docs

This assumes the docs live in the docs directory in the submodule.

Note that in this example there will be a nested docs directory. To make this work properly we need to update sidebars.ts with the correct docs path:

sidebars.ts

const sidebars: SidebarsConfig = {
    ...
  gatewaySidebar: [{type: 'autogenerated', dirName: 'gateway/docs'}],
    ...
}

Checkout update to submodules

Git submodules are not automatically updated, so if you want to pull the latest submodules you need to explicitly update them.

git submodule update --init --recursive