backstage/packages/techdocs-cli/README.md

techdocs-cli

Usage

See techdocs-cli usage docs.

Development

NOTE: When we build techdocs-cli it copies the output techdocs-cli-embedded-app bundle into the packages/techdocs-cli/dist which is then published with the @techdocs/cli npm package.

Running

# From the root of this repository run
# NOTE: This will build the techdocs-cli-embedded-app and copy the output into the cli dist directory
yarn build --scope @techdocs/cli

# Now execute the binary
packages/techdocs-cli/bin/techdocs-cli

# ... or as a shell alias in ~/.zshrc or ~/.zprofile or ~/.bashrc or similar
export PATH=/path/to/backstage/packages/techdocs-cli/bin:$PATH

If you want to test live test changes to the packages/techdocs-cli-embedded-app you can serve the app and run the CLI using the following commands:

# Open a shell to the techdocs-cli-embedded-app directory
cd packages/techdocs-cli-embedded-app

# Run the techdocs-cli-embedded-app using dev mode
yarn start

# In another shell use the techdocs-cli from the root of this repo
yarn techdocs-cli:dev [...options]

Use an example docs project

We have created an example documentation project and it's shipped with techdocs-container repository, for the purpose of local development. But you are free to create your own local test site. All it takes is a docs/index.md and mkdocs.yml in a directory.

git clone https://github.com/backstage/techdocs-container.git

cd techdocs-container/mock-docs

# To get a view of your docs in Backstage, use:
techdocs-cli serve

# To view the raw mkdocs site (without Backstage), use:
techdocs-cli serve:mkdocs

Testing

Running unit tests requires mkdocs to be installed locally:

pip install mkdocs
pip install mkdocs-techdocs-core

Then run yarn test.

Run Cypress tests

Running cypress tests requires you to run the CLI locally against our example docs project

Start by making sure you have the example project locally on your computer

git clone https://github.com/backstage/techdocs-container.git

Run the local version of techdocs-cli against the example docs project

# From the root of this repository run
# NOTE: This will build the techdocs-cli-embedded-app and copy the output into the cli dist directory
yarn build --scope @techdocs/cli

# Navigate to the example project
cd techdocs-container/mock-docs

# Now execute the techdocs-cli binary
../../backstage/packages/techdocs-cli/bin/techdocs-cli

Run the cypress tests

yarn cypress:open