docs: update quickstart

added a few sections (WIP) to make it more complete

docs/userguide/quickstart.txt

@@ -2,20 +2,18 @@
 ``setuptools`` Quickstart
 ==========================
 
+.. contents::
+
 Installation
 ============
 
-.. _Installing Packages: https://packaging.python.org/tutorials/installing-packages/
-
 To install the latest version of setuptools, use::
 
     pip install --upgrade setuptools
 
-Refer to `Installing Packages`_ guide for more information.
 
 Python packaging at a glance
 ============================
-
 The landscape of Python packaging is shifting and ``Setuptools`` has evolved to
 only provide backend support, no longer being the de-facto packaging tool in
 the market. All python package must provide a ``pyproject.toml`` and specify
@@ -27,9 +25,9 @@ change is driven under `PEP 517 <https://www.python.org/dev/peps/pep-0517/#
 build-requirements>``. To learn more about Python packaging in general,
 navigate to the `bottom <Resources on python packaging>`_ of this page.
 
+
 Basic Use
 =========
-
 For basic use of setuptools, you will need a ``pyproject.toml`` with the
 exact following info, which declares you want to use ``setuptools`` to
 package your project:
@@ -62,14 +60,14 @@ This is what your project would look like::
         setup.cfg
         mypackage/__init__.py
 
-Then, you need an installer, such as ``pep517 <https://pypi.org/project/pep517/``
+Then, you need an installer, such as `pep517 <https://pypi.org/project/pep517/>`_
 which you can obtain via ``pip install pep517``. After downloading it, invoke
 the installer::
 
     pep517 build
 
 You now have your distribution ready (e.g. a ``tar.gz`` file and a ``.whl``
-file in the ``dist``), which you can upload to PyPI!
+file in the ``dist`` directory), which you can upload to PyPI!
 
 Of course, before you release your project to PyPI, you'll want to add a bit
 more information to your setup script to help people find or learn about your
@@ -78,9 +76,9 @@ dependencies, and perhaps some data files and scripts. In the next few section,
 we will walk through those additional but essential information you need
 to specify to properly package your project.
 
+
 Automatic package discovery
 ===========================
-
 For simple projects, it's usually easy enough to manually add packages to
 the ``packages`` keyword in ``setup.cfg``.  However, for very large projects
 , it can be a big burden to keep the package list updated. ``setuptools``
@@ -105,9 +103,9 @@ that each entry in the ``[options.packages.find]`` is optional. The above
 setup also allows you to adopt a ``src/`` layout. For more details and advanced
 use, go to :ref:`package_discovery`
 
+
 Entry points and automatic script creation
 ===========================================
-
 Setuptools support automatic creation of scripts upon installation, that runs
 code within your package if you specify them with the ``entry_point`` keyword.
 This is what allows you to run commands like ``pip install`` instead of having
@@ -126,9 +124,9 @@ invoke the ``some_func`` in the ``__init__.py`` file when called by the user.
 For detailed usage, including managing the additional or optional dependencies,
 go to :ref:`entry_point`.
 
+
 Dependency management
 =====================
-
 ``setuptools`` supports automatically installing dependencies when a package is
 installed. The simplest way to include requirement specifiers is to use the
 ``install_requires`` argument to ``setup.cfg``.  It takes a string or list of
@@ -151,9 +149,9 @@ care of those needed by automatically generated scripts. It also provides
 mechanisms to handle dependencies that are not in PyPI. For more advanced use,
 see :ref:`dependency_management`
 
+
 Including Data Files
 ====================
-
 The distutils have traditionally allowed installation of "data files", which
 are placed in a platform-specific location. Setuptools offers three ways to
 specify data files to be included in your packages. For the simpliest use, you
@@ -166,5 +164,27 @@ can simply use the ``include_package_data`` keyword:
 
 This tells setuptools to install any data files it finds in your packages.
 The data files must be specified via the distutils' ``MANIFEST.in`` file.
-
 For more details, see :ref:`datafiles`
+
+
+Uploading your package to PyPI
+==============================
+After generating the distribution files, next step would be to upload your
+distribution so others can use it. This functionality is provided by
+``twine <https://pypi.org/project/twine/>`` and we will only demonstrate the
+basic use here.
+
+
+Transitioning from ``setup.py`` to ``setup.cfg``
+==================================================
+To avoid executing arbitary scripts and boilerplate code, we are transitioning
+into a full-fledged ``setup.cfg`` to declare your package information instead
+of running ``setup()``. This inevitably brings challenges due to a different
+syntax. Here we provide a quick guide to understanding how ``setup.cfg`` is
+parsed by ``setuptool`` to ease the pain of transition.
+
+
+Resources on Python packaging
+=============================
+Packaging in Python is hard. Here we provide a list of links for those that
+want to learn more.