Skip to content

Latest commit

 

History

History
92 lines (70 loc) · 2.59 KB

DEVELOPMENT.adoc

File metadata and controls

92 lines (70 loc) · 2.59 KB

This is the main repository for building the Kaskada docs using antora. This repository reads from two other repositories

  1. kaskada for the contents

  2. docs-ui for the HTML UI components

Prerequisites

  1. NVM

  2. Node

    1. Use nvm to install node

> nvm install --lts

Setup

For local setup this repository provides the file local-antora-playbook.yml that locally overrides antora’s setup to read from local disk rather than fetch the 2 dependent repos. The file locally overrides both content and ui components.

  • Create a new folder to use for your work (e.g., docs-workspace)

  • Go into that folder and checkout this repository and both dependent repositories

> cd docs-workspace
> git clone git@github.com:kaskada-ai/docs-site.git
> git clone git@github.com:kaskada-ai/kaskada.git
> git clone git@github.com:kaskada-ai/docs-ui.git

  • Go into the docs-ui folder and build the bundle

> cd docs-ui
> npm install
> ./node_modules/.bin/gulp bundle

  • Go back into docs-site and build the docs locally

> cd ../docs-site
> npm install
> npx antora --fetch local-antora-playbook.yml --stacktrace

  • If all goes well you should see

Site generation complete!
Open file:///Users/johndoe/docs-workspace/docs-site/build/site/index.html in a browser to view your site.

Paste file:///Users/johndoe/docs-workspace/docs-site/build/site/index.html into your browser’s address bar the local version of the site should render on your browser.

Start making changes

  • if you are adding content,

    1. alter the files in kaskada

    2. come back to docs-site, run the last build command npx …​

    3. hit refresh on your browser window

  • if you are altering the ui components,

    1. alter the files in docs-ui

    2. rebuild the ui bundle inside docs-ui by running ./node_modules/.bin/gulp bundle

    3. come back to docs-site, run the last build command npx …​

    4. hit refresh on your browser window

When you are happy with your changes make sure you commit and open PRs for all changes you made in each repo.

Build targets

For convenience the project also defines the following targets that you can run with npm run <target>

  clean
    rm -rf build
  cleanall
    rm -rf build node_modules
  lb
    npx antora --fetch local-antora-playbook.yml --stacktrace
  lbr
    npm install && npm run lb
  rebuild
    npm run clean && npm run lb