docs: add documentation for PYPI_TOKEN

docs/automatic-releases/index.rst

@@ -64,11 +64,10 @@ upload to pypi and push to git and it should be ready to roll.
 
 Configuring pypi upload
 ^^^^^^^^^^^^^^^^^^^^^^^
-In order to upload to pypi python-semantic-release needs credentials to an account that
-have access to the given package. Either by being logged in through a pip configuration file
-or through environment variables. The latter is most often preferable in an CI environment.
-You will need to set ``PYPI_USERNAME`` and ``PYPI_PASSWORD``. Make sure that you mark it
-as a secret on your CI service so that your password will be left out of the build logs.
+In order to upload to PYPI, Python Semantic Release needs credentials to access
+the project. You will need to set the environment variable :ref:`env-pypi_token`.
+Make sure that you mark it as a secret on your CI service so that it is left out
+of the build logs.
 
 
 .. _automatic-github:

docs/automatic-releases/travis.rst

@@ -16,10 +16,10 @@ You will need to set up three environment variables in Travis. An easy way to do
 is to go to the settings page for your package and add them there. Make sure that the
 secret toggle is set correct for the ones that are secret.
 
-You will need to set ``PYPI_USERNAME`` and ``PYPI_PASSWORD`` with values corresponding
-to a pypi user with access to the given package. Furthermore, you need to set ``GH_TOKEN``
-with a personal access token for Github. It will need either ``repo`` or ``public_repo`` scope
-depending on whether the repository is private or public.
+You will need to set :ref:`env-pypi_token` to a PyPI API token. Furthermore,
+you need to set ``GH_TOKEN`` with a personal access token for Github. It will
+need either ``repo`` or ``public_repo`` scope depending on whether the
+repository is private or public.
 
 More information on how to set environment variables can be found on
 `Travis documentation on environment variables`_.

docs/configuration.rst

@@ -122,6 +122,7 @@ Distributions
 ``upload_to_pypi``
 ------------------
 If set to false the pypi uploading will be disabled.
+See :ref:`env-pypi_token` which must also be set for this to work.
 
 ``upload_to_release``
 ---------------------

docs/envvars.rst

@@ -76,17 +76,35 @@ and click on *Personal access token*.
 A personal access token from GitLab. This is used for authenticating
 when pushing tags, publishing releases etc.
 
+.. _env-pypi_token:
+
+``PYPI_TOKEN``
+--------------
+Set an API token for publishing to https://pypi.org/. Information on how to
+obtain a token is given `here <https://pypi.org/help/#apitoken>`_.
+
+See :ref:`automatic-pypi` for more about PyPI uploads.
+
 .. _env-pypi_password:
 
 ``PYPI_PASSWORD``
 -----------------
 Used together with :ref:`env-pypi_username` when publishing to https://pypi.org/.
 
+.. warning::
+  You should use :ref:`env-pypi_token` instead of username and password
+  authentication for the following reasons:
+
+  - It is `strongly recommended by PyPI <https://pypi.org/help/#apitoken>`_.
+  - Tokens can be given access to only a single project, which reduces the
+    possible damage if it is compromised.
+  - You can change your password without having to update it in CI settings.
+  - If your PyPI username is the same as your GitHub and you have it set
+    as a secret in a CI service, they will likely scrub it from the build
+    output. This can break things, for example repository links.
+
 .. _env-pypi_username:
 
 ``PYPI_USERNAME``
 -----------------
 Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/.
-
-.. note::
-  See :ref:`automatic-pypi` for more about PyPI uploads.