On 16 January 2014 17:46, Marcus Smith <qwc...@gmail.com> wrote:
>>
>> I don't have a clear picture of the split myself but it seems to me
>> that docs.python.org should be the master reference data for
>> *distutils*. That's somewhat screwed, though, as we're recommending
>> use of setuptools, and setuptools messes round so invasively with
>> distutils that the usefulness of pure distutils documentation is
>> limited :-(
>>
>
> docs.python.org should provide a distutils reference, and drop the
> "Installing/Distributing Python Modules" guides in deference to the PUG.
> and setuptools (as an extension of distutils) should provide a *complete*
> index of commands/options that covers everything, not just what it changed
> or added, because it's too hard for users to keep track of what's pure vs
> modified. That's my plan in the refactor of the setuptools docs I'm working
> on.
That makes sense. But I think it's a case of getting people to what
they need as quickly as possible (and having the details available
further on, if they need them). The pip documentation is great for
this. Go to the front page, first thing you see is "Quickstart". First
thing that hits your eye on that page is "pip install
SomePackage==1.0".
Maybe that's what the PUG should have - the very first index entry is
"Quick Start". That points to a page that goes:
Installing a package
==============
Use `pip` to install from `PyPI`:
pip install SomePackage
Creating a project
=============
Install `pip`, `setuptools` and `wheel`. [Question: In the system
python? Introduce virtualenv here?] Create a project structure like
this::
myproject
myproject
__init__.py
setup.py
setup.cfg
tests
README.txt
`Here` is a basic setup.py you can copy and edit.
... etc. (Not too long, but cover the essentials).
In the above, I'm using `...` to mark links to the detailed documentation.
After that "Quick Start" link, the rest of the index can go into the
details however people prefer. It's just that quick start that needs
to be up front.
Maybe I can do a PR for this - would that be useful? I'm lousy at
writing documentation, but if I put a shell in that people can work
from would that help?
Paul
_______________________________________________
Distutils-SIG maillist - Distutils-SIG@python.org
https://mail.python.org/mailman/listinfo/distutils-sig
