Remove mkdocs from project dependencies

[danielfsbarreto]

CrewAI has been using https://mintlify.com/ to serve its docs

No Mintlify capabilities impacted:

(crewai) ➜  docs git:(remove-mkdocs) mintlify dev

✔ Local Mintlify instance is ready. Launching your site...
Your local preview is available at http://localhost:3000
Press Ctrl+C any time to stop the local preview.

warn - No utility classes were detected in your source files. If this is unexpected, double-check the `content` option in your Tailwind CSS configuration.
warn - https://tailwindcss.com/docs/content-configuration

[mplachta]

Disclaimer: This review was made by a crew of AI Agents.

Code Review for crewAIInc/crewAI PR #3036: Remove MkDocs from Project Dependencies

Summary of Key Findings

This PR effectively removes the entire MkDocs-based documentation infrastructure from the repository, replacing it with a Mintlify-based documentation workflow. The following components were removed:

• .github/workflows/mkdocs.yml - the GitHub Actions workflow for building and deploying documentation via MkDocs.
• mkdocs.yml - the MkDocs site configuration, including metadata, theme, navigation, plugins, and markdown extensions.
• MkDocs and related packages removed from pyproject.toml dev dependencies.
• Corresponding MkDocs-related entries fully purged from uv.lock lockfile.

This is a cohesive and consistent cleanup reflecting the project’s migration away from MkDocs towards Mintlify for documentation management and deployment.

Detailed Review and Suggestions

1. .github/workflows/mkdocs.yml (Deleted)

• Positive: The workflow that triggered on release to build/deploy MkDocs docs has been fully removed, matching the shift away from MkDocs.
• Recommendation: Verify no references or integrations remain that call this workflow. If there are developer guides or automation referencing this file or workflow name, update accordingly.
• Suggestion: Document the new documentation deployment process in developer guides or contributing docs to ease contributor transition.

2. mkdocs.yml (Deleted)

• Positive: Removal is straightforward, given MkDocs is no longer used.
• Potential Impact: The removed nav and config defined the entire documentation site structure, navigation, and appearance. If Mintlify docs differ in navigation or available content, contributors and users should be informed.
• Suggestion: Add a note in the README.md or create a /docs/README.md clarifying that documentation is now served and maintained on Mintlify, providing direct links.
• Example snippet:

# Documentation

The CrewAI documentation is now served via [Mintlify](https://mintlify.com/).  
For contributing or accessing docs, visit: https://docs.crewai.com (Mintlify hosted)

3. pyproject.toml (Modified)

• Positive: All MkDocs-related packages (mkdocs, mkdocstrings, mkdocstrings-python, mkdocs-material, mkdocs-material-extensions) have been removed from dev dependencies, cleaning up the environment.
• Suggestion: Consider adding a brief inline comment in pyproject.toml to explain that these packages were removed due to the transition in documentation tooling. This helps future maintainers understand the rationale.

Example:

# MkDocs dependencies removed as documentation now is managed through Mintlify.

• Action: Confirm there are no scripts, Makefile targets, or local dev instructions relying on these packages, to avoid breakage.

4. uv.lock (Modified)

• Positive: Lockfile properly removes all MkDocs package entries, maintaining dependency consistency.
• Recommendation: After lockfile changes, ensure to run dependency sync commands (uv pip sync) to update installed packages.
• Suggestion: Review any CI pipelines or developer onboarding flows to remove MkDocs-related setup steps to prevent confusion or errors.

---

Historical Context & Learnings from Related PRs

• This PR represents a transition from repository-integrated static site generation using MkDocs and GitHub Pages to an external SaaS documentation platform (Mintlify).
• Similar past changes (in other projects) highlight the importance of:
  • Fully removing legacy tools and workflows.
  • Keeping documentation contributors well-informed of new contribution processes.
  • Ensuring all references, URLs, and “edit on GitHub” style links are updated or removed as needed.
• This PR demonstrates good practice in fully eliminating MkDocs-related dependencies and automation with no leftover references in the core manifest and lockfile.

---

Implications for Related Files and Areas

• README.md and CONTRIBUTING.md:
  These should be updated to reflect that documentation contributions and previews now happen via Mintlify, replacing previous MkDocs instructions.

• Documentation folder (/docs) contents:
  If Markdown files structured for MkDocs remain under /docs, consider adding a README.md clarifying their association or repurpose as needed.

• CI/CD and Developer Scripts:
  Examine and clean up any references to MkDocs commands or workflows within CI, local setup scripts, or Makefiles.

---

Specific Improvement Suggestions

• Add contributor-facing documentation about the new documentation workflow:

## Documentation Changes

CrewAI documentation is no longer built or deployed using MkDocs and GitHub Pages.

Docs are now hosted on [Mintlify](https://mintlify.com/):  
- Visit [https://docs.crewai.com](https://docs.crewai.com) to view docs.  
- Contributing guidelines for docs are available at `./docs/mintlify-workflow.md`.

• Annotate pyproject.toml with comments about removed dependencies for context.

• Confirm that all CI/CD pipelines and development documentation are consistent with this new approach.

• If feasible, provide a migration/readme note redirecting users from old GitHub Pages URLs to the Mintlify docs site to prevent confusion.

---

Conclusion

This PR is a well-executed and necessary change aligning CrewAI’s documentation strategy with modern SaaS tooling via Mintlify. The cleanup is thorough, removing all traces of MkDocs-related dependencies, configuration, and workflows.

No functional or code quality problems were detected. The main outstanding task is updating user and contributor documentation to communicate the new process and ensure smooth onboarding.

---

Thank you for this comprehensive and clean removal! Implementing the recommendations above will further improve clarity and developer experience.

[tonykipkemboi]

[joaomdmoura]

Disclaimer: This review was made by a crew of AI Agents.

Code Review Comment

Summary

This pull request effectively removes MkDocs entries from the CrewAI project, evidencing a transition to Mintlify for documentation hosting. The following changes have been made:

• Removal of workflow configuration related to MkDocs.
• Deletion of the primary MkDocs configuration file.
• Update of the project dependencies to align with the new documentation hosting solution.
• Cleanup of the lock file to remove any references to MkDocs packages.

Detailed Observations

1. Workflow Removal (.github/workflows/mkdocs.yml)

• Justification: The removal of this GitHub Actions workflow is appropriate as the automation for MkDocs deployment is no longer necessary.
• Impact: This cleanup aids in reducing complexity for future maintainers and eliminates unnecessary CI/CD steps, streamlining the deployment process.

2. Configuration Removal (mkdocs.yml)

• Justification: The deletion of the MkDocs configuration file is warranted since it is no longer relevant.
• Impact: This action prevents confusion over the project's documentation strategy and clearly delineates that Mintlify is the new system in use.

3. Dependencies Update (pyproject.toml)

• Changes: The following dependencies were effectively removed:

  mkdocs>=1.4.3
  mkdocstrings>=0.22.0
  mkdocstrings-python>=1.1.2
  mkdocs-material>=9.5.7
  mkdocs-material-extensions>=1.3.1

• Recommendations: It is advisable to comment within the pyproject.toml file, indicating that documentation is now handled by Mintlify for clarity:

  # Documentation is now handled by Mintlify (https://mintlify.com/)

4. Lock File Update (uv.lock)

• Justification: The removal of MkDocs-related packages is necessary to maintain an updated and clean project environment.
• Impact: This ensures no outdated dependencies remain that could complicate future builds.

Additional Suggestions

1. Documentation Update: To facilitate smoother transitions and provide clarity, consider adding this note to the README.md:

   ## Documentation
   Our documentation has moved to Mintlify and can be found at https://mintlify.com/docs/crewai

2. Redirect Setup: Implement HTTP redirects from the legacy MkDocs URLs to the new Mintlify documentation to preserve access to existing links.

3. Code Cleanup: Execute a command to ensure all MkDocs-generated files are purged from the codebase:

   git clean -fd docs/

Overall Assessment

✅ LGTM (Looks Good To Merge)

The proposed changes are well-structured and clearly articulated in their purpose. The transition to Mintlify is aptly executed, with no remnants of the previous configuration left behind. This PR streamlines the repository and makes it easier for future contributors to navigate the documentation hosting framework.

Impact Analysis

• 📦 Reduction in dependency size, enhancing security.
• 🚀 A more simplified and less error-prone development and deployment process.
• 📄 Clear adjustment in the documentation strategy with no detectable breaking changes.

This pull request is ready to be merged, pending verification that the Mintlify documentation is properly configured and operational.