diff --git a/README.rst b/README.rst index 6a1e665f..37836808 100644 --- a/README.rst +++ b/README.rst @@ -1,7 +1,7 @@ twine ===== -Twine is a utility for interacting `with PyPI `_. +Twine is a utility for interacting `with PyPI `_. Currently it only supports registering `projects `_ and uploading `distributions `_. @@ -9,25 +9,25 @@ Currently it only supports registering `projects `_ in Python 2.7.9+ and Python 3.2+. This means anytime you use ``python setup.py upload`` with an older Python version, you expose your username and password to being -easily sniffed. Twine uses only verified TLS to upload to PyPI protecting your +easily sniffed. Twine uses only verified TLS to upload to PyPI, protecting your credentials from theft. -Secondly it allows you to precreate your distribution files. +Secondly, it allows you to precreate your distribution files. ``python setup.py upload`` only allows you to upload something that you've created in the same command invocation. This means that you cannot test the exact file you're going to upload to PyPI to ensure that it works before uploading it. -Finally it allows you to pre-sign your files and pass the .asc files into -the command line invocation -(``twine upload twine-1.0.1.tar.gz twine-1.0.1.tar.gz.asc``). This enables you -to be assured that you're typing your gpg passphrase into gpg itself and not -anything else since *you* will be the one directly executing +Finally, it allows you to pre-sign your files and pass the ``.asc`` +files into the command line invocation (``twine upload +twine-1.0.1.tar.gz twine-1.0.1.tar.gz.asc``). This enables you to be +assured that you're typing your ``gpg`` passphrase into ``gpg`` itself +and not anything else, since *you* will be the one directly executing ``gpg --detach-sign -a ``. @@ -35,10 +35,10 @@ Features -------- - Verified HTTPS Connections -- Uploading doesn't require executing setup.py +- Uploading doesn't require executing ``setup.py`` - Uploading files that have already been created, allowing testing of distributions before release -- Supports uploading any packaging format (including wheels). +- Supports uploading any packaging format (including wheels) Installation @@ -58,7 +58,7 @@ Usage $ python setup.py sdist bdist_wheel -2. Upload with twine: +2. Upload with ``twine``: .. code-block:: console @@ -88,7 +88,7 @@ Options optional arguments: -h, --help show this help message and exit -r REPOSITORY, --repository REPOSITORY - The repository to register the package to. Can be a + The repository to upload the package to. Can be a section in the config file or a full URL to the repository (default: pypi). (Can also be set via TWINE_REPOSITORY environment variable) @@ -204,7 +204,7 @@ Contributing 1. Fork the `repository `_ on GitHub. 2. Make a branch off of master and commit your changes to it. -3. Run the tests with ``tox`` +3. Run the tests with ``tox``. - Either use ``tox`` to build against all supported Python versions (if you have them installed) or use ``tox -e py{version}`` to test against a @@ -223,7 +223,8 @@ virtualenv and then do ``pip install -e .`` from within the directory. Code of Conduct --------------- -Everyone interacting in the twine project's codebases, issue trackers, chat -rooms, and mailing lists is expected to follow the `PyPA Code of Conduct`_. +Everyone interacting in the ``twine`` project's codebases, issue +trackers, chat rooms, and mailing lists is expected to follow the +`PyPA Code of Conduct`_. .. _PyPA Code of Conduct: https://www.pypa.io/en/latest/code-of-conduct/ diff --git a/docs/index.rst b/docs/index.rst index 7e8c24b7..ab3a459b 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -11,9 +11,11 @@ Twine is `a utility`_ for interacting with PyPI. Currently it only supports registering `projects`_ and uploading `distributions`_. -The goal is to improve PyPI interaction by improving security and -testability. Ideally, ``pip`` and ``twine`` will merge into a single -tool. +The goal of ``twine`` is to improve PyPI interaction by improving +security and testability. In the future, ``pip`` and ``twine`` may +merge into a single tool; see `discussion +`_ for ongoing +discussion. Please see `the GitHub repository`_ for code and more documentation, and the `Python Packaging User Guide`_ for user documentation. You can @@ -124,4 +126,3 @@ Indices and tables .. _`tox`: https://tox.readthedocs.io/en/latest/ .. _`tox-pipenv`: https://pypi.python.org/pypi/tox-pipenv .. _`plugin`: https://github.com/bitprophet/releases -