ADD: setup techdocs

Author: NewerKey

.github/workflows/cd-workflow.yaml

@@ -1,55 +1,54 @@
-name: Deploy backstage
+name: Deploy Backstage
 
 on:
-  push:
-    branches:
-      - main
-  pull_request:
-    branches:
-      - main
+  workflow_run:
+    workflows: ["CI Workflow"]
+    types:
+      - completed
 
 jobs:
   create-and-push-image:
     permissions:
       id-token: write
-      contents: read
-    name: "Create and push the Docker image to GAR"
+      contents: read  # Remove if not required
+
+    name: "Create and Push Docker Image to GAR"
     runs-on: ubuntu-latest
     defaults:
       run:
         shell: bash
 
     steps:
-      - name: Checkout
+      - name: Checkout Repository
         uses: actions/checkout@v4
 
-      - id: 'setup-qemu'
-        name: Set up QEMU
+      - name: Set up QEMU
+        id: setup-qemu
         uses: docker/setup-qemu-action@v3
 
-      - id: 'docker-buildx-setup'
-        name: Set up Docker Buildx
+      - name: Set up Docker Buildx
+        id: docker-buildx-setup
         uses: docker/setup-buildx-action@v3
 
-      - name: 'Authenticate to Google Cloud'
-        id: 'auth'
-        uses: 'google-github-actions/auth@v2'
+      - name: Authenticate to Google Cloud
+        id: auth
+        uses: google-github-actions/auth@v2
         with:
           create_credentials_file: true
           token_format: "access_token"
           workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
           service_account: ${{ secrets.GCP_DEPLOY_SA }}
 
-      - name: "Login to GAR"
-        id: 'login-gar'
+      - name: Login to GAR
+        id: login-gar
         uses: docker/login-action@v3
         with:
           registry: ${{ secrets.GCP_REGION }}-docker.pkg.dev/${{ secrets.GCP_PROJECT_ID }}/${{ secrets.GCP_GAR_REPO }}
           username: oauth2accesstoken
           password: ${{ steps.auth.outputs.access_token }}
 
-      - id: 'build-and-push'
-        name: 'Build and Push docker Image'
+      - name: Build and Push Docker Image
+        id: build-and-push
         uses: docker/build-push-action@v5
         with:
           push: true
@@ -60,44 +59,45 @@ jobs:
           build-args: |
             APP_ENV=docker
 
-
   deploy-image:
     permissions:
       id-token: write
-      contents: read
+      contents: read  # Remove if not required
 
-    name: "Deploy image on cloud run"
+    name: "Deploy Image on Cloud Run"
     runs-on: ubuntu-latest
+    needs: create-and-push-image
     defaults:
       run:
         shell: bash
-    needs: create-and-push-image
 
     steps:
-      - name: Checkout
+      - name: Checkout Repository
         uses: actions/checkout@v4
 
-      - id: 'auth'
-        name: 'Authenticate to Google Cloud'
-        uses: 'google-github-actions/auth@v2'
+      - name: Authenticate to Google Cloud
+        id: auth
+        uses: google-github-actions/auth@v2
         with:
           create_credentials_file: true
           workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
           service_account: ${{ secrets.GCP_DEPLOY_SA }}
 
       - name: Deploy to Cloud Run
-        id: 'deploy'
-        uses: 'google-github-actions/deploy-cloudrun@v2'
+        id: deploy
+        uses: google-github-actions/deploy-cloudrun@v2
         with:
           service: ${{ secrets.GCP_CLOUD_RUN_SERVICE }}
           image: ${{ secrets.GCP_REGION }}-docker.pkg.dev/${{ secrets.GCP_PROJECT_ID }}/${{ secrets.GCP_GAR_REPO }}/backstage-image:${{ github.sha }}
           region: ${{ secrets.GCP_REGION }}
-          flags: '--platform managed --allow-unauthenticated --port=7007'
-          secrets: |-
+          flags: |
+            --platform managed
+            --allow-unauthenticated
+            --port=7007
+          secrets: |
             GITHUB_TOKEN=github_token:latest
             GITLAB_TOKEN=gitlab_token:latest
             GOOGLE_CLIENT_ID=google_client_id:latest
             GOOGLE_CLIENT_SECRET=google_client_secret:latest
             PROD_GITHUB_CLIENT_SECRET=github_client_secret:latest
             PROD_GITHUB_CLIENT_ID=github_client_id:latest
-            

.gitignore

@@ -57,5 +57,6 @@ pg_values.yaml
 
 *secret.yaml
 
+.vscode/
 
 key/

app-config.yaml

@@ -39,7 +39,7 @@ techdocs:
   generator:
     runIn: 'docker' # Alternatives - 'local'
   publisher:
-    type: 'local' # Alternatives - 'googleGcs' or 'awsS3'. Read documentation for using alternatives.
+    type: 'googleGcs' # Alternatives - 'awsS3', 'azureBlobStorage'
 
 # scaffolder:
 
@@ -56,7 +56,11 @@ catalog:
       rules:
         - allow: [Template]
     - type: file
-      target: ./examples/template/template.yaml
+      target: ./examples/template/register-component.yaml
+      rules:
+        - allow: [Template]
+    - type: file
+      target: ./examples/template/sample-document.yaml
       rules:
         - allow: [Template]
 

catalog-info.yaml

@@ -7,13 +7,14 @@ metadata:
     It also enables users to store, view and discover information about projects in CODE. 
   annotations:
     github.com/project-slug: 'codeuniversity/code-idp'
-  #   backstage.io/techdocs-ref: dir:.
+    backstage.io/techdocs-ref: dir:.
 spec:
   type: website
   owner: code_idp_team
   lifecycle: production
 
 ---
+
 apiVersion: backstage.io/v1alpha1
 kind: Component
 metadata:
@@ -35,4 +36,4 @@ spec:
     displayName: Infrastructure Team
     email: [email protected]
   children: []
-  members: [Yvette]
+  members: [Yvette...]

docs/how-to-publish-documentation.md

@@ -0,0 +1,58 @@
+# How to publish your documentation
+
+You need the following things prepared to document a component:
+
+* A [registered component](./how-to-register-a-component.md) (You can also do
+both setups, registration of the component and the documentation together in
+one go).
+
+## Set the configuration file for MkDocs
+
+* A file named `mkdocs.yml` in the root of the repository.
+
+!!! example "mkdocs.yml file with techdocs configuration"
+
+    ```yaml
+    site_name: Publish Documentation Example
+    docs_dir: docs
+    plugins:
+    - techdocs-core
+    ```
+
+## Add annotation for documentation
+
+You need to create the definition `annotations:` inside the `metadata:` section
+of your component and add the key `backstage.io/techdocs-ref` annotation in the
+`catalog-info.yaml` file.
+
+!!! example "catalog-info.yaml file with techdocs information"
+
+    ```yaml
+    apiVersion: backstage.io/v1alpha1
+    kind: Component
+    metadata:
+      #...
+      annotations:
+        backstage.io/techdocs-ref: dir:.
+      #...
+    ```
+
+## Add documentation
+
+Create a directory called `docs`, define a file called `index.md` or `readme.md`,
+this will be the main page of your documentation.
+
+Inside this you can `docs` directory you should be able to use Markdown files
+`*.md` to define your documentation.
+
+### Formatting and capabilities
+
+Documentation is formatted mainly using [MkDocs syntax](https://www.mkdocs.org/user-guide/writing-your-docs/),
+also with [Material for MkDocs features](https://squidfunk.github.io/mkdocs-material/reference/)
+and some specific features added to [Backstage](https://backstage.io/) as
+plugins.
+
+
+## References
+
+* [TechDocs Documentation in Backstage](https://backstage.io/docs/features/techdocs/)

docs/how-to-register-a-component.md

@@ -1,4 +1,4 @@
-# How to register a component and define service dependency and RTO
+# How to register a component and define service dependency
 
 ## Register a new service(component)
 

docs/index.md

@@ -1,2 +1,18 @@
-# Getting Started with CODE-IDP
+# Getting Started
 
+CODE-IDP is the platform to automate deployment of node and flask applications, centralize software components(Microservices, Websites, Libraries, APIs, Data pipelines, ML models ) and publish technical documentation. 
+
+Current components defined can be found in the [Catalog home]()
+
+Documentation defined per service can be found in the [Documentation section]()
+
+## Deploy your application
+
+- [Quick tutorial to deploy your application](./how-to-deploy-your-app.md)
+
+
+## Register and Document Your Software Projects
+
+- [Register your components](./how-to-register-a-component.md)
+  
+- [Publish documentaion](./how-to-publish-documentation.md)

examples/template/template.yaml renamed to examples/template/register-component.yaml

@@ -0,0 +1,11 @@
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+  name: sample-document
+  annotations:
+    backstage.io/techdocs-ref: dir:.
+spec:
+  type: documentation
+  lifecycle: experimental
+  owner: guests
+  system: examples

examples/template/sample-document.yaml

@@ -0,0 +1,14 @@
+site_name: CODE-IDP Platform
+site_description: This is the user guide for the CODE-IDP platform.
+docs_dir: docs
+nav:
+  - Overview:
+    - Introduction: 'index.md'
+  - Components:
+    - Register Your Software Component: 'how-to-register-a-component.md'
+  - Technical Documentation: 
+    - Publish Your Docs: 'how-to-publish-documentation.md'
+
+plugins: 
+  - techdocs-core
+  - include-markdown