backstage
techdocs-cli
Usage
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 directoryyarn workspace @techdocs/cli build
# Now execute the binarypackages/techdocs-cli/bin/techdocs-cli
# ... or as a shell alias in ~/.zshrc or ~/.zprofile or ~/.bashrc or similarexport 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 directorycd packages/techdocs-cli-embedded-app
# Run the techdocs-cli-embedded-app using dev modeyarn start
# In another shell use the techdocs-cli from the root of this repoyarn techdocs-cli:dev [...options]
Connecting behind a proxy
# Prior to executing the techdocs-cli commandexport GLOBAL_AGENT_HTTPS_PROXY=${HTTP_PROXY}export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}
Using an example docs project
For the purpose of local development, we have created an example documentation project. You are of course also free to create your own local test site - all it takes is a docs/index.md
and an mkdocs.yml
in a directory.
cd packages/techdocs-cli/src/example-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
E2E tests
Running unit tests requires mkdocs to be installed locally:
pip install mkdocspip install mkdocs-techdocs-core
Then run yarn test
.