[docs] Preparing a Change for Requirementshandling in Python projects

[Sandro Tosi]

Hello Erik,
thanks for your interest in making the Python documentation even better.

On Mon, Mar 25, 2013 at 9:32 AM, Erik Bernoth <bernoth at dresearch-fe.de> wrote:
> 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!

Sorry for this quite late reply, I hope this hadn't reduced your
enthusiasm in the Python project.

> 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

that's a really nice skills set!

> Challenges for me
> ===============
>
>  * English isn't my mothertounge (it's German)

no worries, there's a lot of developers writing documentation in
English even if it's not their mother tongue.

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

I think the idea might be good, but I encourage you to write a patch
(even as a draft) to the documentation and post it as a bug in the
Python issues tracking system at: bugs.python.org ; at that point,
people will start discussing your proposal, and you'd get a a wider
audience than this list.

Regards,
--
Sandro Tosi (aka morph, morpheus, matrixhasu)
My website: http://matrixhasu.altervista.org/
Me at Debian: http://wiki.debian.org/SandroTosi