-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
7b5810c
commit 3ba5700
Showing
4 changed files
with
82 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
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 |