fix(mkdocs): structure according best practices (#442)

* fix(mkdocs): structure according best practices

This change structures mkdocs according to their [recommended file
layout][mkdocs-file-layout]. This moves `mkdocs.yml` to the root of the
project, alongside the `docs/` directory.

Also, update the `catalog-info.yml`'s `backstage.io/techdocs-ref`
annotation to `.`. Backstage [strongly recommends `techdocs-ref`
annotation to be set to `dir:.` in almost all
situations][backstage-techdocs-ref].

[mkdocs-file-layout]: https://www.mkdocs.org/user-guide/writing-your-docs/#file-layout
[backstage-techdocs-ref]: https://backstage.io/docs/features/techdocs/how-to-guides/#how-to-understand-techdocs-ref-annotation-values

* fix(publish-docs): remove default-working-directory input and fix paths

This should now be run in the root rather than inside the `docs/` dir.
Also update paths for when workflow should run.
Also fix comment for serving mkdocs locally

.github/workflows/publish-techdocs.yaml

@@ -4,8 +4,8 @@ on:
     branches:
       - main
     paths:
-      - 'docs/docs/**'
-      - 'docs/mkdocs.yml'
+      - 'docs/**'
+      - 'mkdocs.yml'
       - 'catalog-info.yaml'
       - '.github/workflows/publish-techdocs.yaml'
 concurrency:
@@ -19,4 +19,3 @@ jobs:
       namespace: default
       kind: component
       name: Grizzly
-      default-working-directory: ./docs

catalog-info.yaml

@@ -9,7 +9,7 @@ metadata:
     - title: Slack Channel
       url: https://raintank-corp.slack.com/archives/C018SLDD5MW
   annotations:
-    backstage.io/techdocs-ref: dir:./docs
+    backstage.io/techdocs-ref: dir:.
     github.com/project-slug: grafana/grizzly
 spec:
   type: service

docs/mkdocs.yml → mkdocs.yml

@@ -1,10 +1,9 @@
 # To run locally
-# npx techdocs-cli serve -v -c ./docs/mkdocs.yml
+# npx techdocs-cli serve -v -c ./mkdocs.yml
 # 
 site_name: 'Grizzly Internal Documentation'
 repo_url: https://github.com/grafana/grizzly
 edit_uri: edit/main/docs
-docs_dir: .
 
 theme:
   name: material