Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update landing page #326

Merged
merged 7 commits into from Jun 16, 2017

Conversation

@theacodes
Copy link
Member

commented Jun 15, 2017

  • Use friendlier language
  • Be more authoritative
  • Briefly explain the various types of documentation here.

@theacodes theacodes requested review from ddbeck and ncoghlan Jun 15, 2017

@theacodes

This comment has been minimized.

Copy link
Member Author

commented Jun 15, 2017

Towards #317

@ncoghlan
Copy link
Member

left a comment

LGTM, so once the build issue is resolved, I say go ahead and merge it :)

@ncoghlan

This comment has been minimized.

Copy link
Member

commented Jun 16, 2017

Taking a closer look at the build issue, it's just the reminder to update the reference set of deep links.

The "Python Packaging User Guide" (PyPUG) aims to be the authoritative resource
on how to package, publish, and install Python projects using current tools.
Welcome to the *Python Packaging User Guide*. This guide provides documentation
on how to distribute and install Python packages.

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

The revised text here seems to be a lot less clear about what distinguishes this guide from, say, the setuptools or pip docs. If this text is going to change, I'd like to see it be even more reader focused. How about something like Welcome to the *Python Packaging User Guide*, a collection of tutorials and references to help you distribute and install Python packages. Or something like that. We can workshop it a bit. 😃

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

I like it, updated. :)


Additionally, there is a list of :doc:`other projects <key_projects>` maintained by members of the Python Packaging Authority.

Index

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

Index should be Contents

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

Done.


.. _docs.python.org: http://docs.python.org
Get started
===========

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

This (and the following headings) ought to be level 2.

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

They are.

To follow the development of Python packaging, see the `Python
Packaging Authority <https://www.pypa.io>`_.
This guide is maintained on `GitHub`_ by the `Python Packaging Authority`_. We
happily accept any :doc:`contributions and feedback <contribute>`. :)

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

Gratuitous personal preference: change :) to 😄

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

Done.


If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`

More resources

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

If the ToC below is going to show more depth, then I don't think this section is necessary. Skip right to the ToC.

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

I actually want to try to hide the ToC on this page, gotta tweak the theme a bit to get that to work.

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

Okay, toc hidden, you can check it out here: http://temp.theadora.io/pypug-326/index.html

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

OK. I'm not in love with not having the full ToC visible anywhere, but I'll cope. A couple more comments coming up, in this case.

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

Maybe retitle this section as "Learn more" for parallelism with "Get started"

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

done.


If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`

More resources

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

OK. I'm not in love with not having the full ToC visible anywhere, but I'll cope. A couple more comments coming up, in this case.


If you want to learn how to package and distribute your projects, see the :doc:`tutorial on packaging and distributing <tutorials/distributing-packages>`

More resources

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

Maybe retitle this section as "Learn more" for parallelism with "Get started"

* :doc:`guides/index` that walk you through a specific task.
* :doc:`discussions/index` that provide comprehensive documentation on specific topics.
* :doc:`specifications/index` for detailed information about packaging specifications.

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

If these bullets are going to signpost the rest of the ToC, let's be a little be a little more forthcoming about what these sections contain. How about something like this:

* :doc:`guides/index` for walk throughs, such as :doc:`guides/installing-using-linux-tools` or :doc:`guides/packaging-binary-extensions`
* :doc:`discussions/index` for in-depth references on topics such as :doc:`discussions/deploying-python-applications` or :doc:`discussions/pip-vs-easy-install`
* :doc:`specifications/index` for packaging interoperability specifications

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

Good suggestion, done.

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

One minor thing: can we lose the periods on the ends of the bullets? It's a list of things, not really completely sentences

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

Done.

* :doc:`discussions/index` that provide comprehensive documentation on specific topics.
* :doc:`specifications/index` for detailed information about packaging specifications.

Additionally, there is a list of :doc:`other projects <key_projects>` maintained by members of the Python Packaging Authority.

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

members of the Python Packaging Authority -> the Python Packaging Authority

Well, probably? I'm not sure the distinction between members and the PyPA itself is meaningful. I assume it isn't and figure this change would be consistent with the other line about the PyPA above.

This comment has been minimized.

Copy link
@theacodes

theacodes Jun 16, 2017

Author Member

I think it's important here to keep the distinction, some of these projects are rather independent.

This comment has been minimized.

Copy link
@ddbeck

ddbeck Jun 16, 2017

Contributor

OK, sounds good.

@theacodes theacodes force-pushed the theacodes:new-landing-page branch from 088a6bf to 5485e1c Jun 16, 2017

@ddbeck

ddbeck approved these changes Jun 16, 2017

@theacodes

This comment has been minimized.

Copy link
Member Author

commented Jun 16, 2017

Thanks for the review, @ddbeck!

@theacodes theacodes merged commit 78c0d91 into pypa:master Jun 16, 2017

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details

@theacodes theacodes deleted the theacodes:new-landing-page branch Jun 16, 2017

@ncoghlan

This comment has been minimized.

Copy link
Member

commented Jun 17, 2017

I like the update, but it turns out that the paragraph based structure of the Get started section made the tutorial links less obvious to me than the bullet points in the Learn More section.

What do you think about laying out that section something like:

Get Started

Essential tools and concepts for working with the Python Packaging ecosystem are covered in our Tutorials section:

  • to learn how to install packages, see the tutorial on installing packages.
  • to learn how to package and distribute your projects, see the tutorial on packaging and distributing

That way, all 5 of the key links on the page (installation tutorial, publishing tutorial, guides section, discussion section, specification section), would all be highlighted as bullet points.

@ncoghlan

This comment has been minimized.

Copy link
Member

commented Jun 17, 2017

(PR incoming, as I originally didn't write one because I wasn't sure how I thought the section should look, but articulating the question clarified what I actually wanted)

@theacodes

This comment has been minimized.

Copy link
Member Author

commented Jun 17, 2017

@ncoghlan

This comment has been minimized.

Copy link
Member

commented Jun 17, 2017

@jonparrott already reviewed it, but for future reference: #327 :)

ncoghlan added a commit to ncoghlan/python-packaging-user-guide that referenced this pull request Jun 24, 2017

Update landing page (pypa#326)
Use friendlier language
Be more authoritative
Briefly explain the various types of documentation here.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
3 participants
You can’t perform that action at this time.