Skip to content

Documentation compiler / assembler for the Big Bang product by Platform One

Notifications You must be signed in to change notification settings

Noxsios/bb-docs-compiler

Repository files navigation

bb-docs-compiler

Playwright e2e Tests

v2.0 Declarative Edition

Requirements

  • Python v3.9+
  • prettier installed (npm install prettier --location=global)
  • An internet connection

Install

git clone <this repo>

cd <this repo>

pip3 install poetry

poetry config virtualenvs.in-project true

poetry install --no-dev

Demo GIF

Usage

# get help
poetry run bb-docs-compiler -h
Usage: bb-docs-compiler [OPTIONS]

Options:
  -t, --tag TEXT     Build docs from Big Bang tag <tag>
  -b, --branch TEXT  Build docs from Big Bang branch <branch>
  --pre-release      Build for `release-1.X.0` (only for release engineering)
  -c, --clean        Destroy + reset resources after build
  -o, --outdir TEXT  Output build folder, default (site)
  --no-build         Compile the `docs` folder but do not render w/ mkdocs
  -d, --dev          Run `mkdocs serve` after build
  -h, --help         Show this message and exit.

  Built and maintained by @razzle

Usage Examples

# compile docs for latest Big Bang tag, and run dev server
poetry run bb-docs-compiler --dev

# compile docs for <branch> of Big Bang
poetry run bb-docs-compiler --branch <branch>

# compile docs for <tag> of Big Bang
poetry run bb-docs-compiler --tag <tag>

# build assets located in `site`, use python's built in webserver to view them
python3 -m http.server --directory site

Usage in Big Bang's Release Engineering

  1. Follow install instructions

  2. Make sure that the release-1.X.0 branch is created w/ r2d2

  3. Compile the docs for the current pre-release branch

    poetry run bb-docs-compiler --pre-release --no-build
  4. In different terminals, start the dev server and run the playwright e2e tests

    poetry run mkdocs serve
    npm test
  5. Review any failures, refactor tests if need be. Ping @razzle for assistance if needed.

  6. Once tests are passing, navigate to http://localhost:8000 and explore for a bit.

  7. Continue w/ release engineering, rerun steps 3-4 if any cherry-picks affect docs.

About

Documentation compiler / assembler for the Big Bang product by Platform One

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published