Expand reference and user documentation

[dstufft]

• .pypirc - link to the comprehensive documentation at https://docs.python.org/3/distutils/packageindex.html#pypirc and say, for instance, your .pypirc file needs a [pypi] section, and per Mention that twine prompts you for credentials when omitted #118, the documentation should discuss how you can choose to use .pypirc to store the URL of a repo even if you don't want to store credentials.

• No documentation on using keyring? #277 is where we are specifically figuring out what documentation to add about keyring usage, which figures into Update distributing guide to prefer twine's keyring support, and discourage use of pypirc packaging.python.org#297 for the Python Packaging User Guide. I want to both make sure that we have, or link to, comprehensive .pypirc guidance, AND encourage folks to use keyring instead.

• improve twine -h / twine --help invocation (right now you have to invoke as twine upload -h and the twine -h upload error message is misleading)

• improve command help/usage annotations for twine upload to explain that you should upload dist/*

• address no mention whatsoever of testpypi.python.org in docs packaging.python.org#145 and this Twitter conversation by adding a "use Test PyPI" line to the Usage section of the README

• add "when to use this versus when to use flit/zest.releaser" to README

• OS-specific troubleshooting tips, e.g., Issue installing on macOS Sierra #274 (comment) troubleshooting tip for Mac users running with SIP enabled

• a maintainer checklist for making new releases (see Update changelog and bump version for new release #306)

• improve command help/usage annotations/README for twine upload to add instructions for adding a detached GPG signature & uploading it

[erikrose]

In particular, when it said...

% twine upload dist/*
KeyError: Missing 'pypi' section from the configuration file

...at first run, I had no idea what config file it expected. My first guess was a .twinerc, but now I'm leaning toward .pypirc. Apparently, twine needs a [pypi] section in it, which mine lacks despite lots of previous packaging work. Thus, let's be sure to document what it expects in the file.

[exarkun]

Also:

$ twine --help
usage: twine [-h] [--version] command

positional arguments:
  command

optional arguments:
  -h, --help  show this help message and exit
  --version   show program's version number and exit

This not helpful. 😄

[jedie]

https://twine.readthedocs.org is also empty :(

[anentropic]

I only learnt from finding #160 that twine register exists... it's not mentioned on the homepage which passes for docs.

I'm very glad it does, as it provides exactly what I needed

Also confusing is this:

$ ⮀twine upload --help
usage: twine upload [-h] [-r REPOSITORY] [-s] [--sign-with SIGN_WITH]
                    [-i IDENTITY] [-u USERNAME] [-p PASSWORD] [-c COMMENT]
                    [--config-file CONFIG_FILE] [--skip-existing]
                    dist [dist ...]

positional arguments:
  dist                  The distribution files to upload to the repository,
                        may additionally contain a .asc file to include an
                        existing signature with the file upload

vs

$ ⮀twine register --help
usage: twine register [-h] [-r REPOSITORY] [-u USERNAME] [-p PASSWORD]
                      [-c COMMENT] [--config-file CONFIG_FILE]
                      package

positional arguments:
  package               File from which we read the package metadata

So upload needs the dist/* files path as the dist arg. I wasn't sure what I was supposed to pass to the register command as a package though.

I tried passing the setup.py but that was an error. In the end I tried passing the dist/* path and that worked (despite that it was a wildcard and not a 'file' name)... I guess maybe the mypackage.egg-info path would be accepted too?

Again some basic docs would help.

[anentropic]

hmm, the egg-info doesn't seem usable:

$ ⮀twine register --config-file=./.pypirc mypackage.egg-info
Registering package to https://pypi.python.org/pypi
ValueError: Unknown distribution format: 'mypackage.egg-info'

and

$ ⮀twine register --config-file=./.pypirc mypackage.egg-info/PKG-INFO
Registering package to https://pypi.python.org/pypi
ValueError: Unknown distribution format: 'PKG-INFO'

...if it only accepts the same dist/* path as the upload command maybe the command help description should be the same

[SethMMorton]

I notice that this issue is not part of any milestone. Is there no plan to improve/create documentation?

[sigmavirus24]

If there were no plan to do so this issue wouldn't be open. There is no milestone because we aren't going to stall a release on a vague issue

Sent from my Android device with K-9 Mail. Please excuse my brevity.

[annaraven]

will there still be a ~/.pypirc for future versions, especially for pip publish?

[tuukkamustonen]

For anyone arriving here and looking for changelog, it's in the docs folder, see https://github.com/pypa/twine/blob/master/docs/changelog.rst

Also, there is little documentation at https://packaging.python.org/distributing/?highlight=twine#upload-your-distributions but AFAIK no reference documentation, that this ticket is about.

[brainwane]

I'd love reviews of #292 which is the beginning of scratching the surface on this issue.

[brainwane]

A little bit of reference documentation is in #295 and #296 in case people would like to review that.

[brainwane]

I'm a newish Twine maintainer. Thanks for the suggestions for improvement!

A status update:

In July 2017, uploading to pypi.python.org stopped, and now package maintainers can only upload to the new PyPI, pypi.org. Warehouse, the codebase behind the new PyPI, is available as a pre-production site at https://pypi.org, and I'm one of the people working on it. We're making steady progress on the developer roadmap thanks to funding from Mozilla's Open Source Support Program, and it's on its way to fully replacing the legacy PyPI site, I believe, this year. We're currently seeking feedback from package maintainers, including via several IRC livechats/office hours this week, about what does or doesn't work for you in the new interface, and in the next few weeks we'll be doing so with the wider Python developer community.

I'm working on releasing Twine 1.10.0 in the next few days.

We've improved Twine user (and developer) documentation a lot in the past couple months -- see http://twine.readthedocs.io/ which now works, including the changelog. And the Python Packaging User Guide has a lot more material than it used to about .pypirc files and about packaging and uploading with Twine more generally -- see https://packaging.python.org/tutorials/distributing-packages/?highlight=pypirc , https://packaging.python.org/guides/migrating-to-pypi-org/?highlight=pypirc , and https://packaging.python.org/guides/using-testpypi/?highlight=pypirc .

Clearly we need more reference documentation and user help docs, on Twine behavior, .pypirc (although perhaps a comprehensive .pypirc guide should live at https://packaging.python.org ), and Twine internals. I'd welcome issues and pull requests.

I'm editing the original post at the top of this thread with a TODO list.

[brainwane]

I'm working on some relevant improvements in #320. I'm working towards getting 1.10.1 out in the next few days and would strongly welcome doc improvements to get into that release!

[bhrutledge]

Re: .pypirc and keyring, I added some research and possible next steps to pypa/packaging.python.org#297 (comment). See also #118, #340, #216, and #324.

I'm tempted to break this issue up into discrete, actionable issues.

[brainwane]

I'd be happy to see the individual tasks broken out into discrete issues with some kind of docs tag/label.

[jaraco]

Indeed, this issue is something of a laundry list with an unbounded scope, which is part of why it's been around forever. Closing in favor of creating discrete requests (as needed).

[brainwane]

Jason, do you mind if we reopen till someone has time to break these out into individual issues? Maybe @bhrutledge?