[docs] Preparing a Change for Requirementshandling in Python projects

[Erik Bernoth]

Hi Documenters,

some weeks ago I discussed a way to handle installation reqiurements with
the Distutils people [1] and found that the working solution is *not*
described in the documentation [2,3], while what is described in the
documentation is rather confusing and doesn't work. Thus I want to change
that documentation! But because it's my first change to an important
project like Python, I want to make sure about the way to get there. I'd
like your help on this first and hopefully not last change I want to make
to the Python docs!


Prerequisits I bring with me
======================

 * Acceptable Skills with Python (and other programming languages)
 * Wrote different parts of the documentation of a small open source
framework in Sphinx before
 * Ability to create patch files with git, and thus probably also with hg
 * I've read the devguide [4] until and including chapter 7, which led me
to this mailing list
 * An idea about the change I want to make
 * The willingness to see this change to a successful end, even if it takes
days or weeks (actually I already spent some days preparing!)
 * Downloaded and built the CPython 3.4 binary and docs


Challenges for me
===============

 * English isn't my mothertounge (it's German)
 * no plan how to put everything into the different branches yet (verified
the same documentation exists for all w.i.p. python branches)
 * Haven't written the patch file yet


 Problem Details
=============

The chapter 2.4 [2,3] of the distutils documentation has the following
mistakes/problems/unclearness:
 * It describes the usage of an parameter `requires` to the setup()
function, which should tell pip which other packages it needs to install
for the current project to work. That doesn't work.
 * There is another parameter called "install_requires" which does exactly,
what you would expect. If you install the current project to your
virtualenv, then the other packages are downloaded from the pypi server as
well. This one is not mentioned at all.
 * the application of either parameter is pretty much the same, but it is
explained with a lot of text instead of a simple example. The concept isn't
hard to grasp, but the documentation about it is.
 * Some details, like setting spaces at the right points, are not described
precisely enough and are open to interpretation by the learning reader.
Experimenting while learning is nothing people really like to do. They want
to get a clear guide and an example, implement it and see a working result.



Idea for the new version
====================

 1. The list of what you can do (already exists, but change "requires" and
"install_requires"): require, provide and obsolete and a short explanation
what each of them does.
 2. A short example which has all three relationships preferably with a
small diagram (shouldn't be too confusing, because all should be handled
the same way).
 3. The implementation of the corresponding setup() function.
 4. A description of what exactly happens in the setup function.
 5. A description of the grammatical details
 6. A detailed explanation about how to deviate from the example


What I want from you
==================
1) Do you like the idea?
2) Do you agree with the problem?
3) How would you handle the existing but seemingly not working paramter
"requires" and tell the user that he should use "install_requires" instead?
4) How do I go about changing this page for every version? I'd like to
start it for the current default branch and backtrace my way afterwards.
5) Anything unclear?

Cheers,
Erik




[1] http://mail.python.org/pipermail/distutils-sig/2013-February/019743.html
[2]
http://docs.python.org/2.7/distutils/setupscript.html#relationships-between-distributions-and-packages
[3]
http://docs.python.org/3.4/distutils/setupscript.html#relationships-between-distributions-and-packages
[4] http://docs.python.org/devguide/

-- 
Mit freundlichen Grüßen / Kind Regards
Erik Bernoth
Student Assistant, Bachelor of Engineering, Telematics

DResearch Fahrzeugelektronik GmbH
Otto-Schmirgal-Str. 3, D-10319 Berlin, Germany
Tel: +49 (30) 515932 - 220
Fax: +49 (30) 515932 - 77
mailto:bernoth at dresearch-fe.de <mailadresse at dresearch-fe.de>
http://www.dresearch-fe.de
Amtsgericht Berlin Charlottenburg, HRB: 130120 B
Ust.-IDNr. DE273952058; WEEE Reg.-Nr. DE 60230558
Geschäftsführer: Dr. Michael Weber, Werner Mögle
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/docs/attachments/20130325/838ab3fa/attachment-0001.html>