fix mkdocs with more docs best practices

Author: jeffkala

docs/admin/install.md

@@ -2,13 +2,13 @@
 
 Option 1: Install from PyPI.
 
-```
+```bash
 pip install pyntc
 ```
 
 Option 2: Manually install via Poetry.
 
-```
+```bash
 git clone https://github.com/networktocode/pyntc.git
 cd pyntc
 curl -sSL https://install.python-poetry.org | python3 -
@@ -18,5 +18,5 @@ poetry install
 Option 3: Install from a GitHub branch, such as develop as shown below.
 
 ```bash
-$ pip install git+https://github.com/networktocode/pyntc.git@develop
+pip install git+https://github.com/networktocode/pyntc.git@develop
 ```

docs/admin/uninstall.md

@@ -3,5 +3,5 @@
 Uninstall from environment.
 
 ```bash
-$ pip uninstall pyntc
+pip uninstall pyntc
 ```

docs/admin/upgrade.md

@@ -3,5 +3,5 @@
 Upgrade from PyPI.
 
 ```bash
-$ pip install pyntc --upgrade
+pip install pyntc --upgrade
 ```

docs/generate_code_reference_pages.py

@@ -0,0 +1,20 @@
+"""Generate code reference pages."""
+
+from pathlib import Path
+
+import mkdocs_gen_files
+
+for file_path in Path("pyntc").rglob("*.py"):
+    module_path = file_path.with_suffix("")
+    doc_path = file_path.with_suffix(".md")
+    full_doc_path = Path("code-reference", doc_path)
+
+    parts = list(module_path.parts)
+    if parts[-1] == "__init__":
+        parts = parts[:-1]
+
+    with mkdocs_gen_files.open(full_doc_path, "w") as fd:
+        identifier = ".".join(parts)
+        print(f"::: {identifier}", file=fd)
+
+    mkdocs_gen_files.set_edit_path(full_doc_path, file_path)

mkdocs.yml

@@ -14,8 +14,10 @@ theme:
     - "python"
     - "yaml"
   features:
+    - "content.code.annotate"
     - "content.code.copy"
-    - "navigation.indexes"
+    - "content.tabs.link"
+    - "navigation.footer"
     - "navigation.tabs"
     - "navigation.tabs.sticky"
     - "navigation.tracking"
@@ -40,15 +42,26 @@ theme:
       toggle:
         icon: "material/weather-night"
         name: "Switch to light mode"
-extra_css:
-  - "assets/extra.css"
 
 # needed for RTD version flyout menu
 # jquery is not (yet) injected by RTD automatically and it might be dropped
 # as a dependency in the future
 extra_javascript:
   - "https://code.jquery.com/jquery-3.6.0.min.js"
 
+# Since their file size is quite large, we exclude them from the built docs.
+exclude_docs: |
+  /media/*.gif
+
+validation:
+  absolute_links: warn
+  anchors: warn
+  omitted_files: warn
+  unrecognized_links: warn
+
+extra_css:
+  - "assets/extra.css"
+
 extra:
   generator: false
   ntc_sponsor: true
@@ -69,20 +82,41 @@ extra:
       link: "https://twitter.com/networktocode"
       name: "Network to Code Twitter"
 markdown_extensions:
+  - "markdown_version_annotations":
+      admonition_tag: "???"
   - "admonition"
   - "toc":
       permalink: true
   - "attr_list"
+  - "markdown_data_tables":
+      base_path: "docs"
   - "md_in_html"
+  - "pymdownx.details"
+    # Need pymdownx.emoji for Grid icon search
+  - pymdownx.emoji:
+      emoji_index: !!python/name:material.extensions.emoji.twemoji
+      emoji_generator: !!python/name:material.extensions.emoji.to_svg
   - "pymdownx.highlight":
       anchor_linenums: true
   - "pymdownx.inlinehilite"
   - "pymdownx.snippets"
-  - "pymdownx.superfences"
-  - "footnotes"
+  - "pymdownx.superfences":
+      custom_fences:
+        - name: "mermaid"
+          class: "mermaid"
+          format: !!python/name:pymdownx.superfences.fence_code_format
+  - "pymdownx.tabbed":
+      "alternate_style": true
+  - "pymdownx.tilde"
+
 plugins:
   - "search"
-  - "mkdocs-version-annotations"
+  - "gen-files":
+      scripts:
+        - docs/generate_code_reference_pages.py
+  - "glightbox":
+      manual: true # See https://blueswen.github.io/mkdocs-glightbox/flexibility/enable-by-image-or-page/
+  - "section-index"
   - "mkdocstrings":
       default_handler: "python"
       handlers:
@@ -93,8 +127,6 @@ plugins:
             show_root_heading: true
             show_root_members_full_path: true
             show_source: false
-watch:
-  - "README.md"
 
 nav:
   - Overview: "index.md"