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

pip docs refactor #1556

Merged
merged 1 commit into from
Feb 12, 2014
Merged

pip docs refactor #1556

merged 1 commit into from
Feb 12, 2014

Conversation

qwcode
Copy link
Contributor

@qwcode 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
Copy link
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
Copy link
Member

pfmoore commented Feb 11, 2014

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

@dstufft
Copy link
Member

dstufft commented Feb 11, 2014

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

@dstufft
Copy link
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
Copy link
Contributor Author

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
Copy link
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
@qwcode qwcode deleted the docs_refactor branch February 12, 2014 05:58
@lock lock bot added the auto-locked Outdated issues that have been locked by automation label Jun 5, 2019
@lock lock bot locked as resolved and limited conversation to collaborators Jun 5, 2019
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
auto-locked Outdated issues that have been locked by automation
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants