AsTeRICS Docs

Documentation of AsTeRICS.

Configuration

asterics-docs is a VuePress based project that uses a theme based on the Default Theme. Hence, all configuration provided by the Default Theme of VuePress is available in the custom theme.

::: warning

The (true) sources of all VuePress configuration files are located at src/vuepress/and src/vuepress/config.

After setting up the project for editing, building and releasing, asterics-docs copies all relevant files in the folder docs/. The source files for the VuePress configuration are copied to docs/.vuepress during this process.

:::

Sidebar

The configration for the sidebar is specified in src/vuepress/config.js and in the folder src/vuepress/config/sidebar/.

In addition to the sidebar configuration of the VuePress Default Theme, this project contains helper function to assist or automate this process:

• loadSingleSidebar: Loads markdown files from a single directory (excluding subdirectories)
• loadSidebarFrom: Creates multi-level navigation for directories with nested content
• loadSidebarFromWithPath: Creates a flat list of links from a single directory

For better understanding, compare their usage within the existing configuration.

GitHub Workflows

This repository provides following workflows:

• Release: builds and deploys website to https://www.asterics.eu/
• Prerelease: builds and deploys website to https://www.asterics.eu/next/
• Algolia: deletes previous, creates and uploads new index to Algolia

NOTE: Workflow Release runs Algolia after building the website automatically. Don't run workflow Algolia after running Prerelease since it won't have any effect. When running workflow Algolia manually, enable deletion of the previous index to avoid execeeding the allowed amount of index records.

Algolia

To update the search index of Algolia manually, run following command:

docker run -it --env-file=.env -e "CONFIG=$(cat ./src/vuepress/config/algolia.json | jq -r tostring)" algolia/docsearch-scraper

To run this command, you need following tools installed: docker, jq. Additionally, create a file .env and specify following variables:

APPLICATION_ID=<APP_ID>
API_KEY=<API_KEY>

Dependencies

::: warning Make sure you use Node.js v14 before for this setup. :::

Install needed dependencies with

yarn install

or (better)

pnpm install

Release Instructions

TODO: Write instructions

Usage Instructions

Setup asterics-docs using the provided docs tools (cf. DOCS Reference)

# Initialize asterics-docs
$ yarn docs init
$ pnpm run docs init

# Deinitialize asterics-docs
$ yarn docs deinit
$ pnpm run docs deinit

# Setup docs folder
$ yarn docs setup
$ pnpm run docs setup

Change and edit files

# Show status
$ yarn docs status
$ pnpm run docs status

Update changes

# Add files for commit
$ yarn docs add <file|folder> [<file|folder> ...]
$ pnpm run docs add <file|folder> [<file|folder> ...]

# Commit files
$ yarn docs commit
$ pnpm run docs commit

# Push changes to origin
$ yarn docs push
$ pnpm run docs push

NOTE: You can inspect and add files without the docs tool using git in folder setup by the tool.

Configuration Reference

Use variables in file .env to configure the builds

# Deployment
## Host IP address
HOST="127.0.0.1"

## Host port number
PORT=8000

## Path to documentation on server
ENDPOINT="docs"

# docs tool
AUTHOR="Max Mustermann <[email protected]>"
COMMITTER="Madeleine Musterfrau <[email protected]>"

DOCS Reference

Start docs tool using yarn:

yarn docs <command>

For detailed instructions use:

yarn docs <command> --help

DOCS Commands

# Main
yarn docs init
yarn docs setup
yarn docs add
yarn docs commit
yarn docs push

# Supplementary
yarn docs status
yarn docs index
yarn docs convert

TODO

• yarn docs index: user selected entries
• yarn docs pull: basic functionality
• yarn docs push: credential handling
• yarn docs build/devel: required?
• config.js: VERSION mappings