docs: clean typos and add section for repository upload

Add more details and external links

docs/automatic-releases/github-actions.rst

@@ -2,7 +2,7 @@ Setting up python-semantic-release on GitHub Actions
 ====================================================
 
 Python Semantic Release includes a GitHub Action which runs the ``publish``
-command.
+command. The repository is set to `PyPi`.
 
 Inputs
 ------
@@ -14,9 +14,9 @@ Inputs
 +--------------------------+----------------------------------------------------------------------------------------+
 | ``pypi_token``           | See :ref:`env-pypi_token`.                                                             |
 +--------------------------+----------------------------------------------------------------------------------------+
-| ``repository_username``  | See :ref:`env-pypi_username`.                                                          |
+| ``repository_username``  | See :ref:`env-repository_username`.                                                          |
 +--------------------------+----------------------------------------------------------------------------------------+
-| ``repository_password``  | See :ref:`env-pypi_password`.                                                          |
+| ``repository_password``  | See :ref:`env-repository_password`.                                                          |
 +--------------------------+----------------------------------------------------------------------------------------+
 | ``directory``            | A sub-directory to ``cd`` into before running. Defaults to the root of the repository. |
 +--------------------------+----------------------------------------------------------------------------------------+
@@ -49,11 +49,11 @@ Example Workflow
          uses: relekang/python-semantic-release@master
          with:
            github_token: ${{ secrets.GITHUB_TOKEN }}
-           pypi_token: ${{ secrets.PYPI_TOKEN }}
+           repository_username: __token__
+           repository_password: ${{ secrets.PYPI_TOKEN }}
 
-:ref:`env-pypi_token` should be set as a secret on your repository's settings page.
-It is also possible to use username and password authentication in a similar
-fashion.
+:ref:`env-repository_password` should be set as a secret on your repository's settings page.
+It is also possible to use username and password authentication in a similar fashion.
 
 ``concurrency`` is a
 `beta feature of GitHub Actions <https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions#jobsjob_idconcurrency>`_
@@ -90,14 +90,16 @@ multiple projects.
      with:
        directory: ./project1
        github_token: ${{ secrets.GITHUB_TOKEN }}
-       pypi_token: ${{ secrets.PYPI_TOKEN }}
+       repository_username: __token__
+       repository_password: ${{ secrets.PYPI_TOKEN }}
 
    - name: Release Project 2
      uses: relekang/python-semantic-release@master
      with:
        directory: ./project2
        github_token: ${{ secrets.GITHUB_TOKEN }}
-       pypi_token: ${{ secrets.PYPI_TOKEN }}
+       repository_username: __token__
+       repository_password: ${{ secrets.PYPI_TOKEN }}
 
 .. note::
   The release notes posted to GitHub will not currently distinguish which

docs/automatic-releases/index.rst

@@ -69,16 +69,21 @@ Add ``python setup.py publish`` or ``semantic-release publish`` as an after succ
 preferred Continuous Integration service. Ensure that you have configured the CI so that it can
 upload to an artifact repository and push to git and it should be ready to roll.
 
-.. _automatic-pypi:
+.. _automatic-dist-upload:
 
 Configuring distribution upload
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 In order to upload to an artifact repository, Python Semantic Release needs credentials to access
-the project. You will need to set the environment variable :ref:`env-pypi_token` if you use Pypi,
-:ref:`env-repository_username` and :ref:`env-repository_password` otherwise.
-Make sure that you mark it as a secret on your CI service so that it is left out
-of the build logs.
+the project. You will need to set the environment variables :ref:`env-repository_username` and
+:ref:`env-repository_password`. Use :ref:`config-repository_url` to set a custom repository url.
+As an alternative the repository and/or credentials can be configured using the ``~/.pypirc`` file.
 
+.. warning::
+  Make sure to protect any environment variable containing secrets on your CI service.
+
+.. seealso::
+  - `GitLab pypi-repository <https://docs.gitlab.com/ee/user/packages/pypi_repository/>`_ - GitLab example configuration
+  - `The .pypirc file <https://packaging.python.org/specifications/pypirc/>`_ - ``~/.pypirc`` documentation
 
 .. _automatic-github:
 
@@ -134,3 +139,4 @@ that runs the cronjob has push access to the repository and upload access to an
 4. Add cronjob::
 
     /bin/bash -c "cd <path> && source semantic_release/bin/activate && ./publish 2>&1 >> releases.log"
+

docs/automatic-releases/travis.rst

@@ -16,8 +16,9 @@ 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 :ref:`env-pypi_token` to a PyPI API token. Furthermore,
-you need to set :ref:`env-gh_token` with a personal access token for Github. It will
+You will need to set :ref:`env-repository_password` to a PyPI API token and
+:ref:`env-repository_username` to `__token__`.
+Furthermore, you need to set :ref:`env-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.
 

docs/configuration.rst

@@ -363,21 +363,36 @@ Distributions
 
 ``upload_to_pypi``
 ------------------
-.. deprecated:: 7.10.0
+.. deprecated:: 7.20.0
   Please use :ref:`config-upload_to_repository` instead
 
 If set to false the pypi uploading will be disabled.
+
 See :ref:`env-repository` which must also be set for this to work.
 
+Default: `true`
+
 .. _config-upload_to_repository:
 
 ``upload_to_repository``
 ------------------
 If set to false the artifact uploading to repository will be disabled.
+
 See :ref:`env-repository` which must also be set for this to work.
 
 Default: `true`
 
+.. _config-upload_to_pypi_glob_patterns:
+
+``upload_to_pypi_glob_patterns``
+------------------
+.. deprecated:: 7.20.0
+  Please use :ref:`config-dist_glob_patterns` instead
+
+A comma `,` separated list of glob patterns to use when uploading to pypi.
+
+Default: `*`
+
 .. _config-dist_glob_patterns:
 
 ``dist_glob_patterns``
@@ -390,7 +405,21 @@ Default: `*`
 
 ``repository``
 ------------------
-The repository (package index) to upload to. Should be a section in the ``.pypirc`` file.
+The repository (package index) name to upload to. Should be a section in ``~/.pypirc``.
+The repositories `pypi` and `testpypi` are preconfigured.
+
+Default: `pypi`
+
+.. seealso::
+  - `The .pypirc file <https://packaging.python.org/specifications/pypirc/>`_ - ``~/.pypirc`` documentation
+
+.. _config-repository_url:
+
+``repository_url``
+-----------------
+The repository (package index) URL to upload the package to.
+
+See :ref:`automatic-dist-upload` for more about uploads to custom repositories.
 
 .. _config-upload_to_release:
 
@@ -428,14 +457,6 @@ files should be placed manually in the directory configured in
 
 Default: ``python setup.py sdist bdist_wheel``
 
-.. _config-repository_url:
-
-``repository_url``
------------------
-The repository (package index) URL to upload the package to.
-
-Default: ``pypi``
-
 HVCS
 ====
 

docs/envvars.rst

@@ -82,7 +82,7 @@ and click on *Personal access token*.
 A personal access token from GitLab. This is used for authenticating
 when pushing tags, publishing releases etc.
 
-.. _env-repository
+.. _env-repository:
 
 Artifact Repository Authentication
 ==================================
@@ -91,40 +91,25 @@ Artifact Repository Authentication
 
 ``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>`_.
+.. deprecated:: 7.20.0
+  Please use :ref:`env-repository_password` instead
 
-See :ref:`automatic-pypi` for more about PyPI uploads.
-
-.. note::
-  If :ref:`env-pypi_password`, :ref:`env-pypi_username`, and :ref:`env-pypi_token` are not specified credentials from ``$HOME/.pypirc`` will be used.
+Set an API token for publishing to https://pypi.org/.
 
 .. _env-pypi_password:
 
 ``PYPI_PASSWORD``
 -----------------
-.. deprecated:: 7.10.0
-  Please use :ref:`env-repository_username` instead
-
-Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/.
-
-.. warning::
-  You should use :ref:`env-pypi_token` instead of username and password
-  authentication for the following reasons:
+.. deprecated:: 7.20.0
+  Please use :ref:`env-repository_password` instead
 
-  - 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.
+Used together with :ref:`env-pypi_username` when publishing to https://pypi.org/.
 
 .. _env-pypi_username:
 
 ``PYPI_USERNAME``
 -----------------
-.. deprecated:: 7.10.0
+.. deprecated:: 7.20.0
   Please use :ref:`env-repository_username` instead
 
 Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/.
@@ -135,8 +120,26 @@ Used together with :ref:`env-pypi_password` when publishing to https://pypi.org/
 -----------------------
 Used together with :ref:`env-repository_password` when publishing artifact.
 
+.. note::
+  If you use token authentication with `pypi` set this to `__token__`
+
 .. _env-repository_password:
 
 ``REPOSITORY_PASSWORD``
 -----------------------
 Used together with :ref:`env-repository_username` when publishing artifact.
+Also used for token when using token authentication.
+
+.. warning::
+  You should use token authentication 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.
+
+  - Find more information on `how to obtain a token <https://pypi.org/help/#apitoken>`_.

docs/index.rst

@@ -79,13 +79,19 @@ release notes and new versions to GitHub / GitLab:
 - :ref:`env-gh_token` - GitHub personal access token.
 - :ref:`env-gl_token` - GitLab personal access token.
 
-Releasing on PyPI
+Distributing release on PyPI or custom repository
 -----------------
 
-Unless you disable :ref:`config-upload_to_pypi`, Python Semantic Release will
-publish new versions on PyPI. This requires you to obtain an API token
-`here <https://pypi.org/help/#apitoken>`_ and store it in the environment
-variable :ref:`env-pypi_token`.
+Unless you disable :ref:`config-upload_to_repository` (or :ref:`config-upload_to_pypi`),
+Python Semantic Release will publish new versions to `Pypi`. Customization is supported using a
+``~/.pypirc`` file or config setting and environment variables for username and password/token or a
+combination of both.
+Publishing is done using `twine <https://pypi.org/project/twine/>`_.
+
+- :ref:`config-repository` - use repository and/or credentials from ``~/.pypirc`` file
+- :ref:`config-repository_url` - set custom repository url
+- :ref:`env-repository` - provide credentials using environment variables
+- :ref:`automatic-dist-upload` - configuring CI distribution upload
 
 .. include:: commands.rst