pytorch / pytorch/vision

CONTRIBUTING.md improvement: fail to build docs due to depricated `imghdr`

Open
#9,432 2 comments 0 reactions 0 assignees View on GitHub

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:

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

Open the contributing guide

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 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.