Clarification on Sample Repository Structure

Open
#983 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
4/5
Estimated time
3-5 days
Newbie friendliness
35/100
Issue type
Documentation
Clarity
Mostly clear
Activity status
Stale
Tech stack
python
Domain
documentation

Research direction

Start with the Sample Repository section at /writing/structure/ and read the surrounding guidance on setup.py, requirements.txt, Pipfile, virtualenv, context.py, and Makefile. Compare the stated project structure and workflow, then identify which explanations or links need clarification. Done means the section consistently explains its recommendations, alternatives, and the role of each named file.

Written by the indexing model from the issue text.

Description

In Structuring Your Project (/writing/structure/) the section Sample Repository is a little confusing (at least for me).

  1. Stating that this is the way Kenneth Reitz recommends structuring a project is a little confusing. Is there another way? (I'm sure there are) If so, is Reitz's way the de facto standard or is there another standard out there? (Perhaps links to some other popular structures would be helpful)
  2. On the same vein as 1 above, in most areas the guide is opinionated but in this section by stating its the way Reitz does it, it becomes very unopinionated and this sticks out. Does this mean that the authors aren't agreed upon Reitz's methodology?
  3. We haven't talked about setup.py up to this point in the guide. What is it? (https://stackoverflow.com/questions/1471994/what-is-setup-py)
  4. Here it is suggested we use requirements.txt although earlier we are encouraged to use pipenv and its pipfile (although we are also shown how to use virtualenv directly), this is a bit confusing as there is no mention of a pipfile at all. Might be helpful to expand to include some notes on the pipfile and whether we should include both or one over the other.
  5. The suggested project structure doesn't include context.py, but this seems to be as much a core part as the rest of the test files - should this be added?
  6. The section on Makefile is also confusing - there is no reference to Makefile in the initial project structure; when exactly might one use this?
Dominant language
Batchfile
Stars
29.8k
Forks
5.9k
No merged PRs in 30d

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.

More from realpython/python-guide

All issues in realpython/python-guide

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.