CONTRIBUTING.md improvement: fail to build docs due to depricated `imghdr`
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 17.9k
- Forks
- 7.3k
- Avg merge
- 1d 15h
- Merged PRs (30d)
- 13
Description
📚 The doc issue
For my very first contribution I tried to following CONTRIBUTING.md as closely as possible but had the following UX issue:
Building the docs depends on a rather old Sphinx v5.0.0 which needs the deprecated imghdr module (Could not import extension sphinx.builders.epub3 (exception: No module named 'imghdr')). CONTRIBUTING.md however does not mention a version constraint about python. Therefore I needed to downgrade Python and go trought the whole setup process again.
Improvement suggestion:
- Either mentions at the beginning of CONTRIBUTING.md that Python <3.13 is needed
- Or update Sphynx in the docs requirements to a up to date version
In Additon (closely related to my user experience following CONTRIBUTING.md):
- It would be of great benefit having all dev dependencies (and version constraint) in one or several requirements files for easier setup
- Currently, the dependencies are spread across the CONTRIBUTING.md, often without a version specified (e.g. for mypy or pytest)
I'm happy to help with a PR
Suggest a potential alternative/fix
see above
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with CONTRIBUTING.md and docs/requirements.txt, then compare the documented setup with the docs build requirements. Clarify the Python and Sphinx constraints and decide how the development dependencies should be represented; done means a new contributor can follow the documented setup without the imghdr failure.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 45/100