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

pip docs refactor #1556

Merged
merged 1 commit into from Feb 12, 2014

Conversation

Projects
None yet
3 participants
@qwcode
Contributor

qwcode commented Feb 11, 2014

@dstufft, @pfmoore, since this is a big change, I at least want a +0 or +1 from you two.

here it is in built form: http://www.pip-installer.org/en/docs_refactor/index.html

The main thing here is to have a "User Guide" and "Reference Guide" vs the "Usage", "Cookbook", and "Internal Details" sections. The User/Reference distinction is pretty common, and it does the job I think, along with the "Quickstart" we already have.

  • "Usage" --> "Reference Guide"
  • "Internal Details" --> "Reference Guide" (mostly to the pip install section)
  • "Cookbook" --> "User Guide" (with a new "Managing Packages" section that needs some work)

This is also consistent with the Standard Pypa Docs Template that I want all PyPA project docs to follow to appear consistent with each other, which will make the PUG more effective I think,

some details:

  • Old pages have been left as stubs with links to where the new content is.
  • Each pip command has it's own reference page now, vs all commands being on one page
  • "Release Notes" is a first-level section
  • The release notes no longer uses sections (but rather emphasis) to avoid TOC noise (a better idea?)
  • The "Requirements Files" section is updated with "4 common uses"
  • The section on "ImportError: No module named setuptools” (from pip1.4) is now an orphan page that's connected only with a footnote
  • I turned off -W in the docs build, because we have warnings now due to pages not being in the TOC.
  • mentioned the dev irc channel (#pypa)
  • options in the Reference Guide now use .. option:: for better rendering

cc @ncoghlan

@pfmoore

This comment has been minimized.

Member

pfmoore commented Feb 11, 2014

A couple of minor typos:

  1. In User Guide/Configuration/Environment Variables, Dashes (-) have to replaced with is missing a "be"
  2. In User Guide/Non-Recursive Upgrades, the layout of the bullet list of requirements could do with more space after the initial requirement (this could be an issue with the overall style, I guess)

Otherwise, I'm still reviewing but looks good so far.

@pfmoore

This comment has been minimized.

Member

pfmoore commented Feb 11, 2014

+1 from me, this looks good. Thanks for all your work on docs, @qwcode :-)

@dstufft

This comment has been minimized.

Member

dstufft commented Feb 11, 2014

Can we leave -W on, and use :orphan: on the pages that aren't in the TOC?

@dstufft

This comment has been minimized.

Member

dstufft commented Feb 11, 2014

This could be a seperate PR, but we're dropping support for 3.1 with 1.6 yea?

@qwcode

This comment has been minimized.

Contributor

qwcode commented Feb 11, 2014

oh, didn't know about :orphan:. will do.
yes, drop the 3.1. I'm wanting to merge this to master as well, so, will do that separate.

@dstufft

This comment has been minimized.

Member

dstufft commented Feb 11, 2014

Sounds good. +1 from me then.

qwcode added a commit that referenced this pull request Feb 12, 2014

@qwcode qwcode merged commit 14f7003 into develop Feb 12, 2014

1 check was pending

default The Travis CI build is in progress
Details

@qwcode qwcode deleted the docs_refactor branch Feb 12, 2014

@qwcode qwcode referenced this pull request Feb 12, 2014

Closed

refactor pip docs #6

@agronholm agronholm referenced this pull request Jul 25, 2017

Closed

refactor wheel docs #109

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment