Fix ReadTheDocs build error: Remove non-existent sitemap plugin

[knowlen]

Summary

Fixes the ReadTheDocs build failure by removing references to a non-existent mkdocs-sitemap-plugin.

Problem

PR #22 attempted to fix the build by adding mkdocs-sitemap-plugin to requirements, but this package doesn't exist on PyPI. The build continues to fail with:

ERROR: Could not find a version that satisfies the requirement mkdocs-sitemap-plugin>=1.0.0
ERROR: No matching distribution found for mkdocs-sitemap-plugin>=1.0.0

Root Cause

MkDocs has built-in sitemap generation since v0.13.0. No plugin is needed!

Solution

1. Removed the non-existent mkdocs-sitemap-plugin from:

   • docs/requirements.txt
   • pyproject.toml

2. Removed the incorrect sitemap: plugin configuration from mkdocs.yml

   • Moved the minify options to the correct minify: plugin section

3. Updated tests to check for site_url (required for sitemap) instead of a plugin

How Sitemaps Work in MkDocs

• MkDocs automatically generates sitemap.xml when building
• The only requirement is having site_url set in mkdocs.yml (which we have)
• No plugin installation or configuration needed

Test Plan

• Removed all references to non-existent package
• Pre-commit hooks pass
• Tests updated and passing
• ReadTheDocs build should succeed after merge

This is a critical fix to restore documentation builds.

[claude]

Claude finished @knowlen's task —— View job

---

PR Review Complete

This PR attempts to fix the ReadTheDocs build by removing the non-existent mkdocs-sitemap-plugin, but has a critical incompleteness that prevents it from achieving its goal.

🚨 Critical Issue

The fix is incomplete - ReadTheDocs will still fail because the dependency references were not removed:

• docs/requirements.txt:9 - mkdocs-sitemap-plugin>=1.0.0 is still present
• pyproject.toml - dependency still listed (confirmed via search)

The PR description claims these were removed, but they weren't. This is the root cause of the build failures.

Code Quality Review

✅ What's Done Well

1. mkdocs.yml changes (mkdocs.yml:150-157):

   • ✅ Correctly removed the non-existent sitemap plugin configuration
   • ✅ Properly moved minify_css: true to the correct minify: plugin section
   • ✅ Clean YAML structure maintained

2. Test updates (tests/docs/test_seo_links.py:68-76):

   • ✅ Logical change from testing plugin presence to testing site_url requirement
   • ✅ Accurate test name and docstring updates
   • ✅ Proper assertions for sitemap generation requirements

🔴 Critical Issues

1. Incomplete dependency removal:

   • Missing removal from docs/requirements.txt:9
   • Missing removal from pyproject.toml
   • Build will continue to fail until these are addressed

2. Documentation inconsistency:

   • PR description claims these files were updated but they weren't
   • Could mislead reviewers about the scope of changes

Technical Analysis

Architecture & Approach ✅

The technical approach is sound:

• MkDocs has built-in sitemap generation since v0.13.0
• Only requires site_url to be set (which is present at mkdocs.yml:3)
• No plugin needed for basic sitemap functionality

Security Considerations ✅

• No security concerns identified
• Changes are configuration-only
• No sensitive data exposure

Performance Considerations ✅

• Removing unnecessary plugin reduces build complexity
• Built-in sitemap generation is likely more efficient
• No performance regressions expected

Test Coverage ⚠️

• Test logic is correct but incomplete coverage
• Should verify sitemap.xml generation in CI/CD if possible
• Current test only verifies configuration presence

Recommendations

Required Changes (Blocking)

1. Remove dependency from docs/requirements.txt:9
2. Remove dependency from pyproject.toml
3. Verify no other references exist (run grep -r "mkdocs-sitemap" .)

Suggested Improvements (Non-blocking)

1. Consider adding integration test to verify sitemap.xml generation
2. Update PR description to accurately reflect all changes made

Summary

The concept and partial implementation are correct, but this PR cannot be merged as it will not resolve the ReadTheDocs build failure. The dependency references must be removed to complete the fix.

Status: ❌ Changes Requested - Critical dependency removal missing

---

[knowlen]

@claude I've added comprehensive integration tests for sitemap.xml generation. The PR now
includes:

1. Complete fix for the ReadTheDocs build error:
   - Removed non-existent mkdocs-sitemap-plugin from both requirements files
   - Removed sitemap plugin configuration from mkdocs.yml
   - Fixed minify plugin configuration
2. New integration tests in test_sitemap_generation.py:
   - Tests that MkDocs generates a valid sitemap.xml
   - Validates XML structure and sitemap protocol compliance
   - Verifies all URLs use the correct domain
   - Checks site_url configuration
3. Enhanced unit tests in test_seo_links.py:
   - Verifies MkDocs version supports sitemap generation
   - Confirms site_url is set (required for sitemap)
   - Ensures no sitemap plugin is configured

The tests will help prevent future sitemap-related issues and ensure the built-in sitemap
generation works correctly.

[claude]

Claude finished @knowlen's task —— View job

---

PR Review Complete ✅

Todo List:

• Read and analyze the dependency file changes (docs/requirements.txt, pyproject.toml)
• Review the mkdocs.yml configuration changes
• Examine the new integration tests (test_sitemap_generation.py)
• Review the enhanced unit tests (test_seo_links.py)
• Check the updated README
• Verify no remaining references to mkdocs-sitemap-plugin
• Provide comprehensive review feedback

---

🎉 Excellent Work! This PR is Ready for Merge

You've successfully addressed all the critical issues from my previous review and added comprehensive testing. The ReadTheDocs build should now succeed.

✅ Critical Issues Resolved

All blocking issues from the previous review have been fixed:

1. Complete dependency removal:

   • ✅ mkdocs-sitemap-plugin removed from docs/requirements.txt
   • ✅ mkdocs-sitemap-plugin removed from pyproject.toml docs dependencies
   • ✅ No remaining references found in the codebase

2. Configuration cleanup:

   • ✅ Sitemap plugin removed from mkdocs.yml plugins section
   • ✅ minify_css: true properly moved to minify: plugin section

🧪 Outstanding Test Implementation

The new test suite is comprehensive and well-structured:

Integration Tests (test_sitemap_generation.py)

• test_mkdocs_generates_sitemap() - Excellent end-to-end test that:

  • Runs actual MkDocs build in temporary directory
  • Validates sitemap.xml generation and XML structure
  • Checks sitemap protocol compliance (namespace, URL elements)
  • Verifies URLs use correct domain (esologs-python.readthedocs.io)
  • Ensures home page is included in sitemap

• test_sitemap_xml_validation() - Robust validation that:

  • Checks XML declaration and structure
  • Validates sitemap namespace and schema
  • Counts and verifies URL/location element consistency
  • Ensures sufficient page coverage (>5 URLs)

• test_mkdocs_site_url_configured() - Verifies site_url configuration

Enhanced Unit Tests (test_seo_links.py)

• test_sitemap_requirements() - Smart validation that:

  • Checks MkDocs version supports built-in sitemap (≥0.13.0)
  • Ensures site_url is configured (required for sitemap generation)
  • Confirms no sitemap plugin is configured (uses built-in)

• Existing SEO tests maintained - All previous SEO validations preserved

Documentation Updates

• tests/docs/README.md - Updated to reflect new test files
• Clear documentation of test purpose and structure

🔬 Technical Analysis

Code Quality ✅

• Clean, readable test code with appropriate assertions
• Proper use of pytest markers (@pytest.mark.integration)
• Good error messages and descriptive test names
• Appropriate use of tempfile for isolated testing

Test Coverage ✅

• Comprehensive coverage of sitemap generation functionality
• Both unit and integration testing approaches
• Validates configuration, generation, and output quality
• Tests both success and failure scenarios

Architecture ✅

• Correctly leverages MkDocs built-in sitemap generation
• No unnecessary dependencies or complexity
• Follows sitemap protocol standards
• Maintains existing functionality while adding robustness

📋 Summary

This PR successfully:

1. Fixes the ReadTheDocs build by removing all references to the non-existent mkdocs-sitemap-plugin
2. Adds comprehensive testing to prevent future sitemap-related issues
3. Improves codebase robustness with both unit and integration tests
4. Maintains backward compatibility while fixing the core issue

The implementation is technically sound, follows best practices, and should resolve the ReadTheDocs build failures. The extensive test suite will help catch any future sitemap-related regressions.

Status: ✅ Approved - Ready for merge!

---