1. Tarek Ziadé
  2. distribute
  3. Issues
Issue #385 resolved

Documentation not accessible for beginners

Anonymous created an issue

The documentation as it is now is pretty incomprehensible to beginners. In many (all?) places it seems to assume that the user is already familiar with distutils.

The issue breaks down to many small things, but just highlighting the first example (https://pythonhosted.org/setuptools/setuptools.html#basic-use) shows two stumbling blocks: It doesn't even mention the fact that the file is supposed to be named 'setup.py' (it can be inferred by the text blow, though it is far from clear). Also, the 'scripts' argument is used, and seems to be pretty important, even though it is never explained anywhere. Somewhere down there's the section 'https://pythonhosted.org/setuptools/setuptools.html#automatic-script-creation', which does not mention it, leaving the reader puzzled about what he should use.

I (obviously a beginner to setuptools) feel not comfortable enough with setuptools to suggest how a re-write should be worded, but I don't like the thought of reading the documentation of a package (distutils) that I won't be using just to understand the one I will be using.

Since 3rd-party tutorials seem to be sparse at the moment, the official documentation will most certainly be the starting point for newbies. A 'getting started' section that doesn't assume familiarity with distutils would be most welcome; long term however I believe the documentation as a whole should stand on its own.

Many thanks for the work on this package!

Comments (1)

  1. Jason R. Coombs

    Thanks for the comments and concrete suggestions.

    The PYPA is working on a Python Guide to Packaging which seeks to provide a project-agnostic getting-started point for all Python projects. It's a work in progress, but is designed to fulfill the need described in this ticket. If you would like to help with the documentation, we invite you to file bugs or (preferably) make pull requests to the Packaging Guide project.

    I'll make plans to update the setuptools documentation to refer back to the packaging guide for better visibility.

  2. Log in to comment