Add mkdocs spellcheck and doc contribution guide

For kubernetes-sigs#312

Author: artberger

mkdocs.yml

@@ -26,6 +26,34 @@ plugins:
   - macros:
       j2_line_comment_prefix: "#$"
   - mermaid2
+  - spellcheck:
+      backends:
+      - symspellpy
+      - codespell:
+          dictionaries: [clear, rare, en-GB_to_en-US]
+      # known_words can also be a list of words
+      known_words: known_words.txt
+      # ignore words in <code> tags
+      ignore_code: yes
+      # minimum length of words to consider
+      min_length: 2
+      # maximum number of capital letters in a word
+      max_capital: 1
+      # keep unicode characters
+      allow_unicode: no
+      # skip all directories except docs and site-src
+      skip_files:
+      - api/*
+      - client-go/*
+      - cmd/*
+      - config/*
+      - hack/*
+      - internal/*
+      - pkg/*
+      - test/*
+      - tools/*
+      # whether to only check in strict mode
+      strict_only: no
 markdown_extensions:
   - admonition
   - meta
@@ -48,9 +76,9 @@ nav:
   - Overview:
     - Introduction: index.md
     - Concepts:
-        API Overview: concepts/api-overview.md
-        Conformance: concepts/conformance.md
-        Roles and Personas: concepts/roles-and-personas.md
+      - API Overview: concepts/api-overview.md
+      - Conformance: concepts/conformance.md
+      - Roles and Personas: concepts/roles-and-personas.md
     - Implementations: implementations.md
     - FAQ: faq.md
   - Guides:
@@ -68,3 +96,4 @@ nav:
   - Contributing:
     - How to Get Involved: contributing/index.md
     - Developer Guide: contributing/devguide.md
+    - Docs Guide: contributing/docs.md

site-src/.mkdocs-exclude

@@ -4,3 +4,4 @@
 search/search_index.json
 sitemap.xml.gz
 sitemap.xml
+known_words.txt

site-src/contributing/docs.md

@@ -0,0 +1,66 @@
+# Contributing to the docs
+
+## mkdocs
+
+This doc site is built using MkDocs.
+
+Before you begin, make sure that you have a recent version of `python` and `pip`. You also might want to set up a Python virtual environment for the `gateway-api-inference-extension` project.
+
+To install and use `mkdocs`, refer to the [MkDocs User Guide](https://www.mkdocs.org/user-guide/).
+
+### Set up mkdocs
+
+```sh
+# Install mkdocs
+pip install mkdocs
+
+# Install the Material theme that this project uses
+pip install mkdocs-material
+
+# Install the plugins that this project uses
+pip install mkdocs-awesome-pages-plugin
+pip install mkdocs-macros-plugin
+pip install mkdocs-mermaid2-plugin
+pip install mkdocs-spellcheck
+
+```
+
+### Preview local changes
+
+1. Make your changes to the docs. If you add a new page, make sure to update the `nav` section in the `mkdocs.yml` file.
+
+2. Serve the docs locally.
+   
+    `mkdocs serve`
+
+3. Open the local address that the docs are served from in your browser: [http://127.0.0.1:8000/](http://127.0.0.1:8000/)
+
+## Spellcheck
+
+The project uses [MkDocs SpellCheck](https://pawamoy.github.io/mkdocs-spellcheck/).
+
+1. Install the spellcheck with the backends. The ticks are added for shells that otherwise interpret the `[]` as a command.
+
+    `pip install 'mkdocs-spellcheck[codespell]' && pip install 'mkdocs-spellcheck[symspellpy]'`
+
+2. Build the docs to trigger the spellcheck.
+
+    `mkdocs build`
+
+3. Review the output for `mkdocs_spellcheck` warnings, such as the following example. Notice that the output includes the file name, mispelled word, and suggestions.
+
+    `WARNING -  mkdocs_spellcheck: (symspellpy) index.md: Misspelled 'dont', did you mean 'done'...?`
+
+4. If the word is correct, you can update the [`site-src/known_words.txt` file](../known_words.txt).    
+
+## Publish the docs
+
+The project uses Netlify to host the docs. 
+
+You can locally build the files that become the doc site. For example, you might want to check the HTML output of changes that you make to the site.
+
+```sh
+make build-docs-netlify
+```
+
+The Gateway API Inference Extension team will publish the docs based on the latest changes in the `main` branch.

site-src/known_words.txt

@@ -0,0 +1,59 @@
+AI
+alphanumerics
+API
+APIs
+backend
+backends
+backreference
+composable
+config
+configs
+customizable
+dev
+enum
+enums
+fixups
+fixup
+frontend
+GitHub
+github
+golang
+html
+http
+https
+HTTPRoute
+InferencePool
+InferencePools
+InferenceModel
+InferenceModels
+kgateway
+kubebuilder
+Kubernetes
+kubernetes
+lifecycle
+LLM
+LLMs
+LoRA
+mkdocs
+namespace
+Netlify
+ok
+OpenAI
+passcode
+tradeoff
+tradeoffs
+Triton
+quickstart
+repo
+rollout
+rollouts
+sheddable
+SIG
+SIGs
+sigs
+subproject
+syncer
+uncomment
+vLLM
+WG
+www