wso2 / wso2/docs-api-platform

[Bug]: Local development setup fails on a fresh clone due to missing setuptools pin

Open Beginner friendly
#492 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Type/Bug
Dominant language
HTML
Stars
2
Forks
64
Avg merge
1d 9h
Merged PRs (30d)
34

Description

Description

On a fresh clone, pip install -r requirements.txt succeeds but
python -m mkdocs build fails with:

ModuleNotFoundError: No module named 'pkg_resources'

markdown==3.2.1 requires pkg_resources, which setuptools removed in
version 82.0.0. setuptools is not pinned in en/requirements.txt, so pip
installs the latest version.

The Dockerfile already pins setuptools<80, so container builds are fine —
only local setup is broken. Existing contributors don't see this because their
virtual environments already have an older setuptools.

Fix: add setuptools<80 to en/requirements.txt to match the Dockerfile.

Steps to Reproduce
  1. Clone the repository:
   git clone https://github.com/wso2/docs-api-platform.git
  1. Create and activate a virtual environment:
   cd docs-api-platform
   python3 -m venv venv
   source venv/bin/activate
  1. Install the dependencies:
   cd en
   pip install -r requirements.txt
  1. Build the site:
   python -m mkdocs build

Result: the build fails with:

   File ".../site-packages/markdown/core.py", line 26, in <module>
       import pkg_resources
   ModuleNotFoundError: No module named 'pkg_resources'
Version

main @ 5aab8ab

Environment Details (with versions)

OS: Ubuntu 24.04
Python 3.12.11, pip 26.2.1, setuptools 84.0.0, markdown 3.2.1, mkdocs 1.4.2

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with en/requirements.txt and compare its dependency pins with the existing setuptools<80 pin in the Dockerfile. Recreate the fresh virtual-environment setup, run pip install -r requirements.txt, and verify python -m mkdocs build completes without the pkg_resources error.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Bug
Difficulty
1/5
Estimated time
Under an hour
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
92/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.