Neurophysiologically Pseudoscientific Manatee

    @therynamo/techdocs-cli

    0.0.1 • Public • Published

    techdocs-cli

    NPM Version badge

    Usage

    See techdocs-cli usage docs.

    Development

    Set up locally

    To setup the project for local development, clone this repository, install dependencies and build a local version of the CLI.

    git clone https://github.com/backstage/techdocs-cli
    
    cd techdocs-cli/
    
    yarn install
    
    yarn build

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

    If you're changing files inside @backstage/techdocs-common locally and want to run it locally with techdocs-cli you can run:

    cd backstage/packages/techdocs-common`
    yarn link

    The backstage folder above is from the main Backstage repo

    And then inside the techdocs-cli repo:

    yarn link "@backstage/techdocs-common"

    When you're done, remember to unlink the package so you can use the published version again:

    yarn unlink "@backstage/techdocs-common" && yarn install --force

    Running

    You can now run the CLI:

    # execute the CLI from the root of the repo
    yarn cli
    
    # or using the techdoc-cli binary directly
    packages/techdocs-cli/bin/techdocs-cli
    
    # ... or as a shell alias in ~/.zshrc or ~/.zprofile or ~/.bashrc or similar
    export PATH=/path/to/repo/packages/techdocs-cli/bin:$PATH

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

    # Open a shell
    yarn start:app
    
    # In another shell use the techdocs-cli
    yarn cli:dev [...options]

    Testing

    Running unit tests requires mkdocs to be installed locally:

    pip install mkdocs
    pip install mkdocs-techdocs-core

    Then run yarn test.

    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

    Contributing

    We love having contributions, so if you want to contribute, please:

    1. Create a new Pull Request from your branch to the main

    2. If you want to include your changes in the next version bump, run:

    yarn changeset
    1. Choose a package, semver version, add a summary of the changes and press ENTER

    2. This script will create a new markdown file in the .changeset folder

      Not sure what this means? Click here to learn what changesets are

    3. Commit the changeset along with your PR changes.

    Release

    This repository uses changesets for a more automated release process. All changes to the packages of this repository, packages/embedded-techdocs-app and packages/techdocs-cli should have changesets added along with each change.

    Once you decide you want to do a release:

    Manual release

    1. yarn changeset version This consumes all changesets, and updates to the most appropriate semver version based on those changesets. It also writes changelog entries for each consumed changeset.

    When you have verified the version and changelogs looks as expected, you can publish the new version:

    1. yarn changeset publish

    Automated release

    We have automated these two steps in our main workflow.

    1. The main.yml workflow opens a new PR for you with the package versions and updated changelogs.

    2. This PR can then be merged and if the new version is not published to NPM, the publish step in the main.yml workflow will get triggered and publish the new version for you.

    Note: The Backstage app and plugins versions are fixed in the packages/embedded-techdocs-app mono-repo. So @backstage/plugin-techdocs version may need upgrading from time to time if significant APIs are changed.

    Install

    npm i @therynamo/techdocs-cli

    DownloadsWeekly Downloads

    1

    Version

    0.0.1

    License

    Apache-2.0

    Unpacked Size

    457 kB

    Total Files

    99

    Last publish

    Collaborators

    • therynamo