projectsyn / component-hub

Project Syn Commodore Component Hub

Project Syn Commodore Hub Generator

This project uses the GitHub API to generate an Antora website containing the documentation of all Commodore components and Commodore packages.

How to Use

1. Create an API token in GitHub

2. Use the GITHUB_TOKEN=xxx make command, where xxx is the token retrieved in the previous step.

3. You can use make clean to get rid of the generated website.

Start hacking on the generator

The generator is implemented in Python. The project uses [Poetry] to manage the Python virtual environment. The project sources environment variables from file .env if it exists.

Setup

The Makefile provides a target to setup the poetry environment.

make setup

Run the generator locally

Simply run make hub to generate a local copy of the site in ./build/component-hub/_public

You can run the individual generation steps in isolation:

• poetry run component-hub generate antora-site generates the Antora site from the VSHN Antora Cookiecutter template.

• poetry run component-hub generate index generates docs/modules/ROOT/pages/index.adoc for the component hub.

• poetry run component-hub generate nav generates docs/modules/ROOT/nav.adoc for the component hub.

• poetry run component-hub generate playbook generates playbook.yml for the component hub.

Linting and testing

The Makefile provides targets for Python linting and testing.

make lint
make test

The lint and test targets expect that the Poetry environment is already initialized.

The tests require a Github token in environment variable GITHUB_TOKEN. The tests source environment variables from file `.env if it exists.