Merge pull request #39 from dsj7419/fix/doc-errors

ci: fix documentation build errors

.github/workflows/documentation.yml

@@ -15,7 +15,7 @@ on:
       - "**.md"
       - "mkdocs.yml"
       - "requirements-docs.txt"
-  workflow_dispatch: # Allow manual triggers
+  workflow_dispatch:
 
 jobs:
   build:
@@ -36,22 +36,21 @@ jobs:
           python -m pip install --upgrade pip
           pip install -r requirements-docs.txt
 
-      - name: Install git
+      - name: Check documentation
         run: |
-          sudo apt-get update
-          sudo apt-get install -y git
-
-      - name: Configure Git
-        run: |
-          git config --global user.name "github-actions[bot]"
-          git config --global user.email "github-actions[bot]@users.noreply.github.com"
+          python scripts/check_docs.py
 
       - name: Build documentation
-        run: mkdocs build --strict --verbose
+        run: |
+          mkdocs build --strict --verbose
+        env:
+          GOOGLE_ANALYTICS_KEY: ${{ secrets.GOOGLE_ANALYTICS_KEY }}
 
-      - name: Deploy to GitHub Pages
+      - name: Deploy Documentation
         if: github.ref == 'refs/heads/main' && github.event_name == 'push'
         run: |
+          git config --global user.name "github-actions[bot]"
+          git config --global user.email "github-actions[bot]@users.noreply.github.com"
           mkdocs gh-deploy --force
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

mkdocs.yml

@@ -4,6 +4,7 @@ site_author: dsj7419
 repo_url: https://github.com/dsj7419/gyntree
 repo_name: GynTree
 edit_uri: edit/main/docs/
+site_dir: site
 
 theme:
   name: material
@@ -48,8 +49,9 @@ plugins:
       minify_js: true
       minify_css: true
   - git-revision-date-localized:
-      enable_creation_date: true
       type: date
+      fallback_to_build_date: true
+      enable_creation_date: true
 
 markdown_extensions:
   - admonition
@@ -75,7 +77,6 @@ markdown_extensions:
   - tables
   - toc:
       permalink: true
-      permalink_title: Anchor link to this section
       toc_depth: 3
 
 nav:
@@ -90,23 +91,21 @@ nav:
   - Contributing: contributing/guidelines.md
   - Changelog: changelog.md
 
+validation:
+  nav:
+    omitted_files: warn
+    not_found: error
+    absolute_links: error
+
 extra:
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/dsj7419/gyntree
   analytics:
     provider: google
     property: !ENV GOOGLE_ANALYTICS_KEY
-  consent:
-    title: Cookie consent
-    description: >-
-      We use cookies to recognize your repeated visits and preferences, as well
-      as to measure the effectiveness of our documentation and whether users
-      find what they're searching for. With your consent, you're helping us to
-      make our documentation better.
+  version:
+    provider: mike
+  generator: false
 
-validation:
-  nav:
-    omitted_files: warn
-    not_found: warn
-    absolute_links: warn
+copyright: Copyright © 2024 dsj7419

scripts/check_docs.py

@@ -0,0 +1,47 @@
+"""Script to check documentation files for common issues."""
+import os
+import sys
+from pathlib import Path
+
+def check_docs():
+    """Check documentation files for common issues."""
+    docs_dir = Path("docs")
+    errors_found = False
+
+    # Check for required files
+    required_files = [
+        "index.md",
+        "getting-started/installation.md",
+        "getting-started/faq.md",
+        "user-guide/basic-usage.md",
+        "user-guide/configuration.md",
+        "api/overview.md",
+        "contributing/guidelines.md",
+        "changelog.md"
+    ]
+
+    for file_path in required_files:
+        full_path = docs_dir / file_path
+        if not full_path.exists():
+            print(f"Error: Required file missing: {file_path}")
+            errors_found = True
+        else:
+            # Check if file has content
+            content = full_path.read_text()
+            if not content.strip():
+                print(f"Error: File is empty: {file_path}")
+                errors_found = True
+
+            # Check for broken internal links
+            links = [line for line in content.split("\n") if "[" in line and "]" in line]
+            for link in links:
+                if "](/" in link:  # Internal link
+                    link_path = link.split("](")[-1].split(")")[0].lstrip("/")
+                    if not (docs_dir / link_path).exists():
+                        print(f"Error: Broken internal link in {file_path}: {link_path}")
+                        errors_found = True
+
+    return 0 if not errors_found else 1
+
+if __name__ == "__main__":
+    sys.exit(check_docs())