Skip to content

Commit

Permalink
Merge pull request #16 from monta-app/chore/add-support-for-backstage
Browse files Browse the repository at this point in the history
  • Loading branch information
JesperTerkelsen authored Apr 8, 2024
2 parents b294cad + 3ba5700 commit 0d70d6c
Show file tree
Hide file tree
Showing 4 changed files with 82 additions and 0 deletions.
44 changes: 44 additions & 0 deletions .github/workflows/backstage_techdocs.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,44 @@
name: Publish TechDocs Site

on:
push:
branches: [main]
paths:
- "docs/**"
- "mkdocs.yml"
workflow_dispatch:


jobs:
publish-techdocs-site:
runs-on: ubuntu-latest

env:
TECHDOCS_S3_BUCKET_NAME: 'monta-tech-docs'
AWS_ACCESS_KEY_ID: ${{ secrets.TECHDOCS_AWS_ACCESS_KEY_ID }}
AWS_SECRET_ACCESS_KEY: ${{ secrets.TECHDOCS_AWS_SECRET_ACCESS_KEY }}
AWS_REGION: 'eu-west-1'
ENTITY_NAMESPACE: 'default'
ENTITY_KIND: 'Component'
ENTITY_NAME: ${{ github.event.repository.name }}

steps:
- name: Checkout code
uses: actions/checkout@v4

- uses: actions/setup-node@v4
- uses: actions/setup-python@v5
with:
python-version: '3.9'

- name: Install techdocs-cli
run: sudo npm install -g @techdocs/cli

- name: Install mkdocs and mkdocs plugins
run: python -m pip install mkdocs-techdocs-core==1.*

- name: Generate docs site
run: techdocs-cli generate --no-docker --verbose

- name: Publish docs site
run: techdocs-cli publish --publisher-type awsS3 --storage-name $TECHDOCS_S3_BUCKET_NAME --entity $ENTITY_NAMESPACE/$ENTITY_KIND/$ENTITY_NAME
19 changes: 19 additions & 0 deletions catalog-info.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
# Name of the project
name: otel-extension
description: Open Telemetry Extension
# Specifies the directory of the docs
annotations:
backstage.io/techdocs-ref: dir:.

# The spec defines who becomes the owner of the system in backstage
spec:
type: library
# See lifecycle common values: https://backstage.io/docs/features/software-catalog/descriptor-format/#speclifecycle-required
lifecycle: production
# Name of the squad responsible for the project, e.g. sre or cpi
owner: OCPP
# Name of the greater system, e.g. "solar" is a part of the home system
system: CPI
11 changes: 11 additions & 0 deletions docs/index.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
# Introduction to TechDocs and mkdocs.yaml

TechDocs is a tool used for generating beautiful documentation websites directly from your code repositories. It simplifies the process of creating and maintaining documentation for your projects. One of the key components of TechDocs is `mkdocs.yaml`, a configuration file that allows you to customize various aspects of your documentation site.

## mkdocs.yaml

`mkdocs.yaml` is a YAML configuration file used by MkDocs, the static site generator behind TechDocs. It allows you to define the structure, appearance, and behavior of your documentation website.

In Backstage, the open-source platform for building developer portals, TechDocs is integrated seamlessly, and `mkdocs.yaml` is utilized to configure the documentation site generated by TechDocs.

Inside `mkdocs.yaml`, you can specify various settings such as site title, navigation structure, theme customization, and more. This configuration file plays a crucial role in tailoring your documentation site to meet your project's specific requirements and preferences, providing a seamless experience for your users.
8 changes: 8 additions & 0 deletions mkdocs.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# This file is used to index the docs in the ./docs directory
site_name: 'service documentation'

nav:
- Home: index.md

plugins:
- techdocs-core

0 comments on commit 0d70d6c

Please sign in to comment.