publish contributor docs with mkdocs (hashicorp#19883)

dvob · Jan 12, 2023 · b1d2f57 · b1d2f57
1 parent 2e73f77
commit b1d2f57
Show file tree

Hide file tree

Showing 24 changed files with 109 additions and 18 deletions.
diff --git a/.github/workflows/mkdocs.yml b/.github/workflows/mkdocs.yml
@@ -0,0 +1,20 @@
+name: Publish docs via GitHub Pages
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Publish Contributor GitHub Pages
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+
+      - name: Publish
+        uses: mhausenblas/mkdocs-deploy-gh-pages@master
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          CONFIG_FILE: mkdocs.yml
diff --git a/contributing/README.md b/contributing/README.md
@@ -20,29 +20,30 @@ More granular documentation covers how these fit together - and the most common
 
 Basics:
 
-* [High-level overview of the Provider](topics/high-level-overview.md).
-* [Building the Provider](topics/building-the-provider.md).
-* [Running the Tests](topics/running-the-tests.md).
-* [Our recommendations for opening a Pull Request](topics/guide-opening-a-pr.md).
-* [Debugging the Provider](topics/debugging-the-provider.md).
-* [Frequently Asked Questions](topics/frequently-asked-questions.md).
+* [High-level overview of the Provider](topics/high-level-overview.md)
+* [Building the Provider](topics/building-the-provider.md)
+* [Running the Tests](topics/running-the-tests.md)
+* [Debugging the Provider](topics/debugging-the-provider.md)
+* [Frequently Asked Questions](topics/frequently-asked-questions.md)
+* [Opening a PR](topics/guide-opening-a-pr.md)
 
 Common Topics/Guides:
 
-* [Adding a new Service Package](topics/guide-new-service-package.md).
-* [Adding a new Data Source](topics/guide-new-data-source.md).
-* [Adding a new Resource](topics/guide-new-resource.md).
-* [Adding fields to an existing Data Source](topics/guide-new-fields-to-data-source.md).
-* [Adding fields to an existing Resource](topics/guide-new-fields-to-resource.md).
-* [Opening a PR](topics/guide-opening-a-pr.md).
+* [Adding a new Service Package](topics/guide-new-service-package.md)
+* [Adding a new Data Source](topics/guide-new-data-source.md)
+* [Adding a new Resource](topics/guide-new-resource.md)
+* [Adding fields to an existing Data Source](topics/guide-new-fields-to-data-source.md)
+* [Adding fields to an existing Resource](topics/guide-new-fields-to-resource.md)
+* [When to create a new Resource vs Inline Block](topics/guide-new-resource-vs-inline.md)
 
 References:
 
-* [Acceptance Testing](topics/reference-acceptance-testing.md).
-* [Working with Errors](topics/reference-errors.md).
-* [Glossary](topics/reference-glossary.md).
-* [Naming](topics/reference-naming.md).
+* [Acceptance Testing](topics/reference-acceptance-testing.md)
+* [Working with Errors](topics/reference-errors.md)
+* [Glossary](topics/reference-glossary.md)
+* [Naming](topics/reference-naming.md)
+* [Schema Design](topics/schema-design-considerations.md)
 
 Maintainer specific:
 
-* [Updates to the Changelog](topics/maintainer-changelog.md).
+* [Updates to the Changelog](topics/maintainer-changelog.md)
diff --git a/contributing/extra.css b/contributing/extra.css
@@ -0,0 +1,3 @@
+.md-footer__inner:not([hidden]) {
+    display: none
+}
diff --git a/contributing/images/hashicorp-black.png b/contributing/images/hashicorp-black.png
diff --git a/contributing/images/hashicorp.png b/contributing/images/hashicorp.png
diff --git a/contributing/topics/building-the-provider.md b/contributing/topics/building-the-provider.md
diff --git a/contributing/topics/debugging-the-provider.md b/contributing/topics/debugging-the-provider.md
diff --git a/contributing/topics/frequently-asked-questions.md b/contributing/topics/frequently-asked-questions.md
diff --git a/contributing/topics/guide-new-data-source.md b/contributing/topics/guide-new-data-source.md
diff --git a/contributing/topics/guide-new-fields-to-data-source.md b/contributing/topics/guide-new-fields-to-data-source.md
diff --git a/contributing/topics/guide-new-fields-to-resource.md b/contributing/topics/guide-new-fields-to-resource.md
diff --git a/contributing/topics/guide-new-resource-vs-inline.md b/contributing/topics/guide-new-resource-vs-inline.md
diff --git a/contributing/topics/guide-new-resource.md b/contributing/topics/guide-new-resource.md
diff --git a/contributing/topics/guide-new-service-package.md b/contributing/topics/guide-new-service-package.md
diff --git a/contributing/topics/guide-opening-a-pr.md b/contributing/topics/guide-opening-a-pr.md
diff --git a/contributing/topics/high-level-overview.md b/contributing/topics/high-level-overview.md
@@ -10,7 +10,7 @@ Each of these Data Sources and Resources has both Acceptance Tests and Documenta
 
 The Azure Provider is a large codebase which has evolved over time - but tends to follow consistent patterns for the most-part.
 
-The Provider is split up into Service Packages (see [terminology](basic-glossary.md)) - with some other logic sprinkled across several packages.
+The Provider is split up into Service Packages (see [terminology](reference-glossary.md)) - with some other logic sprinkled across several packages.
 
 At a high-level, the Provider structure is:
 

diff --git a/contributing/topics/maintainer-changelog.md b/contributing/topics/maintainer-changelog.md
diff --git a/contributing/topics/reference-acceptance-testing.md b/contributing/topics/reference-acceptance-testing.md
diff --git a/contributing/topics/reference-errors.md b/contributing/topics/reference-errors.md
diff --git a/contributing/topics/reference-glossary.md b/contributing/topics/reference-glossary.md
diff --git a/contributing/topics/reference-naming.md b/contributing/topics/reference-naming.md
diff --git a/contributing/topics/running-the-tests.md b/contributing/topics/running-the-tests.md
diff --git a/contributing/topics/schema-design-considerations.md b/contributing/topics/schema-design-considerations.md
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -0,0 +1,67 @@
+site_name: Terraform AzureRM Provider - Contributor Guide
+site_description: 'Contributor documentation and reference for the Terraform AzureRM Provider'
+copyright: HashiCorp
+
+repo_name: hashicorp/terraform-provider-azurerm
+repo_url: https://github.com/hashicorp/terraform-provider-azurerm
+edit_uri: "https://github.com/hashicorp/terraform-provider-azurerm/tree/main/contributing"
+
+docs_dir: contributing
+site_dir: site
+
+dev_addr: 127.0.0.1:47000
+
+nav:
+  - Welcome: README.md
+  - Basics:
+      - Overview of the Provider: topics/high-level-overview.md
+      - Building the Provider: topics/building-the-provider.md
+      - Debugging the Provider: topics/debugging-the-provider.md
+      - Running Tests: topics/running-the-tests.md
+      - Opening a Pull Request: topics/guide-opening-a-pr.md
+  - Guides:
+      - Adding a new Service Package: topics/guide-new-service-package.md
+      - Adding a new Data Source: topics/guide-new-data-source.md
+      - Adding a new Resource: topics/guide-new-resource.md
+      - Adding fields to an existing Data Source: topics/guide-new-fields-to-data-source.md
+      - Adding fields to an existing Resource: topics/guide-new-fields-to-resource.md
+      - When to create a new Resource vs Inline Block: topics/guide-new-resource-vs-inline.md
+  - Reference:
+    - Acceptance Testing: topics/reference-acceptance-testing.md
+    - Working with Errors: topics/reference-errors.md
+    - Naming: topics/reference-naming.md
+    - Schema Design: topics/schema-design-considerations.md
+    - Glossary: topics/reference-glossary.md
+  - Maintainers:
+    - Updates to the Changelog: topics/maintainer-changelog.md
+  - FAQ: topics/frequently-asked-questions.md
+
+theme:
+  name: material
+  logo: images/hashicorp.png
+  favicon: images/hashicorp-black.png
+  palette:
+    scheme: hashicorp
+    primary: black
+    accent: blue
+  icon:
+    repo: fontawesome/brands/github
+  font: false
+  features:
+    - navigation.instant
+    - content.tabs.link
+
+plugins:
+  - search:
+      lang:
+        - en
+
+markdown_extensions:
+  - pymdownx.highlight
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+  - toc:
+      permalink: "#"
+
+extra_css:
+  - extra.css