Deleting legacy contents from core install guide?
I finally started working on the docs.python.org updates for PEP 453 tonight, and I'm just not seeing much salvageable information in http://docs.python.org/3/install/index.html. While it was a big step forward back in 1998, it seems to me that it has simply been left unmaintained for too long, and I think leaving that content in there for 3.4 will do more harm than good. The content won't be lost: not only will it continue to exist in source control, but I won't be touching the 2.x docs at http://docs.python.org/2/install/index.html. With that content gone from the end user installation guide in 3.4+, it can become just a very, very simple introduction to the core pip commands, and then a reference out to the packaging user guide for more info. Thoughts? Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
On 23 February 2014 11:43, Nick Coghlan <ncoghlan@gmail.com> wrote:
With that content gone from the end user installation guide in 3.4+, it can become just a very, very simple introduction to the core pip commands, and then a reference out to the packaging user guide for more info.
Thoughts?
Are "setup.py install" and "setup.py build" being officially relegated to undocumented status? That's a genuine question, I don't have a particular reason to object if the answer is "yes". But if they aren't, will there still be documentation anywhere that covers: 1. Running setup.py install will install your project.[1] 2. The locations of the distutils.cfg files. 3. How to use mingw on Windows, including setting the compiler in distutils.cfg.[3] [1] Ideally, that should also explain what this *doesn't* do in comparison to pip. But that's a matter of enhancing the documentation rather than removing legacy stuff. [2] Given that mingw support has some long-standing bugs and issues, it may be that it doesn't even work any more. But if that's true, we should officially desupport it and mark all the relevant bugs as closed/wontfix. If it *is* supported, though, we need to make sure that somewhere we explain how to build with mingw. (At the moment, pip says nothing on the matter, relying on the user setting his default compiler appropriately, which means via the instructions in this section, I guess). That may be something for the PUG, so moving this content to the PUG might be reasonable. I agree on the general principle of getting rid of stuff that's outdated and we don't want to support, but "it's still in the 3.3 docs and source control" isn't quite enough - we need to be clear that we are effectively making stuff undocumented. Paul
On 23 February 2014 22:00, Paul Moore <p.f.moore@gmail.com> wrote:
On 23 February 2014 11:43, Nick Coghlan <ncoghlan@gmail.com> wrote:
With that content gone from the end user installation guide in 3.4+, it can become just a very, very simple introduction to the core pip commands, and then a reference out to the packaging user guide for more info.
Thoughts?
Are "setup.py install" and "setup.py build" being officially relegated to undocumented status? That's a genuine question, I don't have a particular reason to object if the answer is "yes".
But if they aren't, will there still be documentation anywhere that covers:
1. Running setup.py install will install your project.[1] 2. The locations of the distutils.cfg files. 3. How to use mingw on Windows, including setting the compiler in distutils.cfg.[3]
[1] Ideally, that should also explain what this *doesn't* do in comparison to pip. But that's a matter of enhancing the documentation rather than removing legacy stuff. [2] Given that mingw support has some long-standing bugs and issues, it may be that it doesn't even work any more. But if that's true, we should officially desupport it and mark all the relevant bugs as closed/wontfix. If it *is* supported, though, we need to make sure that somewhere we explain how to build with mingw. (At the moment, pip says nothing on the matter, relying on the user setting his default compiler appropriately, which means via the instructions in this section, I guess). That may be something for the PUG, so moving this content to the PUG might be reasonable.
You're right it still needs to be documented, but the problem I ran into is that it no longer has any place in a document like the install guide, which is primarily aimed at end users, including sysadmins that may not care about Python in particular, but just want to know how to install Python packages to a build root so they can create a platform specific package. However, after thinking a little more on the challenge, I believe the lower level legacy content should fit right in as a new subsection in the distutils docs at http://docs.python.org/3/distutils/index.html. Cleaning *that* up can then be part of the longer term project of sorting out the build side of the story, letting me focus on the install side for the 3.4 docs. Cheers, Nick. -- Nick Coghlan | ncoghlan@gmail.com | Brisbane, Australia
However, after thinking a little more on the challenge, I believe the lower level legacy content should fit right in as a new subsection in the distutils docs at http://docs.python.org/3/distutils/index.html.
There's 3 things right now: 1. http://docs.python.org/3/distutils/index.html ("Installing Python Modules") 2. http://docs.python.org/3/install/index.html ("Distributing Python Modules") 3. http://docs.python.org/3/library/distutils.html ("28.15. distutils") I was thinking that #1 and #2 should disappear (or just provide a link to the PUG). I don't think you should bother to recreate any more guides in the python.org docs. The valuable "reference" content in #1 and #2 should be refactored into #3. I'm willing to work on a patch for this, if you agree.
1. http://docs.python.org/3/distutils/index.html ("Installing Python Modules") 2. http://docs.python.org/3/install/index.html ("Distributing Python Modules")
woops, I reversed the links for these.
However, after thinking a little more on the challenge, I believe the lower level legacy content should fit right in as a new subsection in the distutils docs at http://docs.python.org/3/distutils/index.html.
There's 3 things right now:
1. http://docs.python.org/3/distutils/index.html ("Installing Python Modules") 2. http://docs.python.org/3/install/index.html ("Distributing Python Modules") 3. http://docs.python.org/3/library/distutils.html ("28.15. distutils")
I was thinking that #1 and #2 should disappear (or just provide a link to
I don't think you should bother to recreate any more guides in the
On 24 Feb 2014 07:48, "Marcus Smith" <qwcode@gmail.com> wrote: the PUG). python.org docs.
The valuable "reference" content in #1 and #2 should be refactored into #3.
I'd like to keep 1 & 2, but in the form of a high level introduction to their respective areas, including the difference between the standard library and third party modules, and the role redistributors play in the Python ecosystem. Aside from the fact I think that information is useful to end users, and needs to be conveyed in the official docs to give it the necessary authority, my other rationale for that is that I would like to keep the respective links in the top level overview page for the Python docs, as well as avoid breaking any existing deep links to those pages. It also ensures we have at least basic documentation in the offline help files.
I'm willing to work on a patch for this, if you agree.
I do like the idea of moving most of the distutils docs into the distutils module reference. If you were willing to handle that task, that would be brilliant - I'd then focus on writing *new* content for the installation and distribution overview pages that introduces open source development principles, PyPI, the Python Packaging Authority and the Python Packaging User Guide. Cheers, Nick.
I'm willing to work on a patch for this, if you agree.
I do like the idea of moving most of the distutils docs into the distutils module reference.
If you were willing to handle that task, that would be brilliant - I'd then focus on writing *new* content
ok, I'll see what I can come up with. Marcus
On Sun, Feb 23, 2014 at 1:48 PM, Marcus Smith <qwcode@gmail.com> wrote:
However, after thinking a little more on the challenge, I believe the lower level legacy content should fit right in as a new subsection in the distutils docs at http://docs.python.org/3/distutils/index.html.
There's 3 things right now:
1. http://docs.python.org/3/distutils/index.html ("Installing Python Modules") 2. http://docs.python.org/3/install/index.html ("Distributing Python Modules") 3. http://docs.python.org/3/library/distutils.html ("28.15. distutils")
I was thinking that #1 and #2 should disappear (or just provide a link to the PUG). I don't think you should bother to recreate any more guides in the python.org docs. The valuable "reference" content in #1 and #2 should be refactored into #3.
To be explicit about one aspect of this process, I think content we want documented going forward should only be removed once the information has been added in its replacement form. For example, for stuff moving to PUG, I don't think we should remove a section from "Distributing Python Modules" if the information we want there is not yet in PUG. A lot of PUG is still in a skeletal state. By the way, I noticed that PUG's "Installation & Packaging Tutorial" [1] is one section. Shouldn't those be separate tutorials? IIRC that information was in separate sections before (one for installing and one for packaging). --Chris [1] http://python-packaging-user-guide.readthedocs.org/en/latest/tutorial.html
I was thinking that #1 and #2 should disappear (or just provide a link to the PUG). I don't think you should bother to recreate any more guides in the python.org docs. The valuable "reference" content in #1 and #2 should be refactored into #3.
To be explicit about one aspect of this process, I think content we want documented going forward should only be removed once the information has been added in its replacement form. For example, for stuff moving to PUG, I don't think we should remove a section from "Distributing Python Modules" if the information we want there is not yet in PUG.
I agree, but again, my thinking is to refactor a lot of the content in #1 and #2, into #3, not necessarily move it to the PUG. For example, details on the distutils install schemes and config files would be in #3, not directly in the PUG.
By the way, I noticed that PUG's "Installation & Packaging Tutorial" [1] is one section. Shouldn't those be separate tutorials? IIRC that information was in separate sections before (one for installing and one for packaging).
that's gone back and forth a bit. at first it was 2 separate tutorials, then 2 tutorials and quickstart, then just a quickstart, and I just recently re-labeled the quickstart as a "tutorial" after a dicussion on IRC, where it seemed odd to have a "quickstart" without a more detailed tutorial later. the tutorial is still developing. maybe it could be split into 2 pages later. I'm more concerned with actually getting content now.
On Sun, Feb 23, 2014 at 2:50 PM, Marcus Smith <qwcode@gmail.com> wrote:
By the way, I noticed that PUG's "Installation & Packaging Tutorial" [1] is one section. Shouldn't those be separate tutorials? IIRC that information was in separate sections before (one for installing and one for packaging).
that's gone back and forth a bit. at first it was 2 separate tutorials, then 2 tutorials and quickstart, then just a quickstart, and I just recently re-labeled the quickstart as a "tutorial" after a dicussion on IRC, where it seemed odd to have a "quickstart" without a more detailed tutorial later. the tutorial is still developing. maybe it could be split into 2 pages later. I'm more concerned with actually getting content now.
Yeah, that history still shows. The first section called "Install the Tools" is only about installing the tools needed for installation. Later sections have you installing other "tools" like wheel and twine when you get to the parts about packaging. There is also no clear separation between when the page switches from the installation parts to the packaging parts (e.g. so users interested only in installing can see more immediately what they need to be reading). --Chris
Yeah, that history still shows. The first section called "Install the Tools" is only about installing the tools needed for installation.
Well, for packaging, minimally you'll need setuptools, and we recommend using get-pip or pip to install setuptools. And if you're going to work in "develop mode", you'll often do that in a virtual environment, and you'll need pip to get virtualenv (at least using a "normal" installation of virtualenv) But what we can do is add all the "tools" to this section (i.e. add twine and wheel) to this section, and be more clear on what's needed for what.
There is also no clear separation between when the page switches from the installation parts to the packaging parts
I hear you, but otoh, if a section says "Create your own project", it's about creating a project, not installation. I guess I'd personally like to see it filled out more before deciding on chopping it up *again*.
participants (4)
-
Chris Jerdonek -
Marcus Smith -
Nick Coghlan -
Paul Moore