Merge pull request #2584 from amy-lei/tabbed-code

Add mechanism for comparison of setup.py and its equivalent setup.cfg

3 files changed, 223 insertions, 160 deletions

diff --git a/docs/userguide/dependency_management.rst b/docs/userguide/dependency_management.rst
index 0eb21864..6108d9b2 100644
--- a/docs/userguide/dependency_management.rst
+++ b/docs/userguide/dependency_management.rst
@@ -49,23 +49,27 @@ be able to run. ``setuptools`` support automatically download and install
 these dependencies when the package is installed. Although there is more
 finess to it, let's start with a simple example.
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    #...
-    install_requires =
-        docutils
-        BazSpam ==1.1
+    .. code-block:: ini
+
+        [options]
+        #...
+        install_requires =
+            docutils
+            BazSpam ==1.1
+
+.. tab:: setup.py
 
-.. code-block:: python
+    .. code-block:: python
 
-    setup(
-        #...,
-        install_requires = [
-            'docutils',
-            'BazSpam ==1.1'
-        ]
-    )
+        setup(
+            #...,
+            install_requires = [
+                'docutils',
+                'BazSpam ==1.1'
+            ]
+        )
 
 
 When your project is installed (e.g. using pip), all of the dependencies not
@@ -82,41 +86,49 @@ specific dependencies. For example, the ``enum`` package was added in Python
 3.4, therefore, package that depends on it can elect to install it only when
 the Python version is older than 3.4. To accomplish this
 
-.. code-block:: ini
-
-    [options]
-    #...
-    install_requires =
-        enum34;python_version<'3.4'
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        install_requires=[
-            "enum34;python_version<'3.4'",]
-    )
+        install_requires =
+            enum34;python_version<'3.4'
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            install_requires=[
+                "enum34;python_version<'3.4'",]
+        )
 
 Similarly, if you also wish to declare ``pywin32`` with a minimal version of 1.0
 and only install it if the user is using a Windows operating system:
 
-.. code-block:: ini
-
-    [options]
-    #...
-    install_requires =
-        enum34;python_version<'3.4'
-        pywin32 >= 1.0;platform_system=='Windows'
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        install_requires=[
-            "enum34;python_version<'3.4'",
-            "pywin32 >= 1.0;platform_system=='Windows'"
-            ]
-    )
+        install_requires =
+            enum34;python_version<'3.4'
+            pywin32 >= 1.0;platform_system=='Windows'
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            install_requires=[
+                "enum34;python_version<'3.4'",
+                "pywin32 >= 1.0;platform_system=='Windows'"
+                ]
+        )
 
 The environmental markers that may be used for testing platform types are
 detailed in `PEP 508 <https://www.python.org/dev/peps/pep-0508/>`_.
@@ -181,20 +193,24 @@ The ``dependency_links`` option takes the form of a list of URL strings.  For
 example, this will cause a search of the specified page for eggs or source
 distributions, if the package's dependencies aren't already installed:
 
-.. code-block:: ini
-
-    [options]
-    #...
-    dependency_links = http://peak.telecommunity.com/snapshots/
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        dependency_links=[
-            "http://peak.telecommunity.com/snapshots/"
-        ],
-    )
+        dependency_links = http://peak.telecommunity.com/snapshots/
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            dependency_links=[
+                "http://peak.telecommunity.com/snapshots/"
+            ],
+        )
 
 
 Optional dependencies
@@ -211,24 +227,28 @@ ancillary functions such as "tests" and "docs".
 For example, Package-A offers optional PDF support and requires two other
 dependencies for it to work:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = Package-A
+    .. code-block:: ini
 
-    [options.extras_require]
-    PDF = ReportLab>=1.2; RXP
+        [metadata]
+        name = Package-A
 
+        [options.extras_require]
+        PDF = ReportLab>=1.2; RXP
 
-.. code-block:: python
 
-    setup(
-        name="Project-A",
-        #...
-        extras_require={
-            "PDF":  ["ReportLab>=1.2", "RXP"],
-        }
-    )
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            name="Project-A",
+            #...
+            extras_require={
+                "PDF":  ["ReportLab>=1.2", "RXP"],
+            }
+        )
 
 The name ``PDF`` is an arbitary identifier of such a list of dependencies, to
 which other components can refer and have them installed. There are two common
@@ -236,31 +256,35 @@ use cases.
 
 First is the console_scripts entry point:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = Project A
-    #...
+    .. code-block:: ini
 
-    [options]
-    #...
-    entry_points=
-        [console_scripts]
-        rst2pdf = project_a.tools.pdfgen [PDF]
-        rst2html = project_a.tools.htmlgen
-
-.. code-block:: python
-
-    setup(
-        name = "Project-A"
-        #...,
-        entry_points={
-            "console_scripts": [
-                "rst2pdf = project_a.tools.pdfgen [PDF]",
-                "rst2html = project_a.tools.htmlgen",
-            ],
-        }
-    )
+        [metadata]
+        name = Project A
+        #...
+
+        [options]
+        #...
+        entry_points=
+            [console_scripts]
+            rst2pdf = project_a.tools.pdfgen [PDF]
+            rst2html = project_a.tools.htmlgen
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            name = "Project-A"
+            #...,
+            entry_points={
+                "console_scripts": [
+                    "rst2pdf = project_a.tools.pdfgen [PDF]",
+                    "rst2html = project_a.tools.htmlgen",
+                ],
+            }
+        )
 
 This syntax indicates that the entry point (in this case a console script)
 is only valid when the PDF extra is installed. It is up to the installer
@@ -273,24 +297,28 @@ The second use case is that other package can use this "extra" for their
 own dependencies. For example, if "Project-B" needs "project A" with PDF support
 installed, it might declare the dependency like this:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = Project-B
-    #...
+    .. code-block:: ini
 
-    [options]
-    #...
-    install_requires =
-        Project-A[PDF]
+        [metadata]
+        name = Project-B
+        #...
+
+        [options]
+        #...
+        install_requires =
+            Project-A[PDF]
+
+.. tab:: setup.py
 
-.. code-block:: python
+    .. code-block:: python
 
-    setup(
-        name="Project-B",
-        install_requires=["Project-A[PDF]"],
-        ...
-    )
+        setup(
+            name="Project-B",
+            install_requires=["Project-A[PDF]"],
+            ...
+        )
 
 This will cause ReportLab to be installed along with project A, if project B is
 installed -- even if project A was already installed.  In this way, a project
diff --git a/docs/userguide/package_discovery.rst b/docs/userguide/package_discovery.rst
index de4ef668..842ade82 100644
--- a/docs/userguide/package_discovery.rst
+++ b/docs/userguide/package_discovery.rst
@@ -19,36 +19,44 @@ Package Discovery and Namespace Package
 support for namespace package. Normally, you would specify the package to be
 included manually in the following manner:
 
-.. code-block:: ini
-
-    [options]
-    #...
-    packages =
-        mypkg1
-        mypkg2
+.. tab:: setup.cfg
 
-.. code-block:: python
+    .. code-block:: ini
 
-    setup(
+        [options]
         #...
-        packages = ['mypkg1', 'mypkg2']
-    )
+        packages =
+            mypkg1
+            mypkg2
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            packages = ['mypkg1', 'mypkg2']
+        )
 
 This can get tiresome reallly quickly. To speed things up, we introduce two
 functions provided by setuptools:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    packages = find:
-    #or
-    packages = find_namespace:
+    .. code-block:: ini
 
-.. code-block:: python
+        [options]
+        packages = find:
+        #or
+        packages = find_namespace:
 
-    from setuptools import find_packages
-    #or
-    from setuptools import find_namespace_packages
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        from setuptools import find_packages
+        #or
+        from setuptools import find_namespace_packages
 
 
 Using ``find:`` or ``find_packages``
@@ -71,30 +79,34 @@ it, consider the following directory
 To have your setup.cfg or setup.py to automatically include packages found
 in ``src`` that starts with the name ``pkg`` and not ``additional``:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    packages = find:
-    package_dir =
-        =src
+    .. code-block:: ini
 
-    [options.packages.find]
-    where = src
-    include = pkg*
-    exclude = additional
+        [options]
+        packages = find:
+        package_dir =
+            =src
 
-.. code-block:: python
+        [options.packages.find]
+        where = src
+        include = pkg*
+        exclude = additional
 
-    setup(
-        #...
-        packages = find_packages(
-            where = 'src',
-            include = ['pkg*',],
-            exclude = ['additional',]
-        ),
-        package_dir = {"":"src"}
-        #...
-    )
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        setup(
+            #...
+            packages = find_packages(
+                where = 'src',
+                include = ['pkg*',],
+                exclude = ['additional',]
+            ),
+            package_dir = {"":"src"}
+            #...
+        )
 
 
 .. _Namespace Packages:
@@ -195,17 +207,21 @@ following:
 
 And the ``namespace_packages`` keyword in your ``setup.cfg`` or ``setup.py``:
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [options]
-    namespace_packages = timmins
+    .. code-block:: ini
 
-.. code-block:: python
+        [options]
+        namespace_packages = timmins
+
+.. tab:: setup.py
+
+    .. code-block:: python
 
-    setup(
-        # ...
-        namespace_packages = ['timmins']
-    )
+        setup(
+            # ...
+            namespace_packages = ['timmins']
+        )
 
 And your directory should look like this
 
diff --git a/docs/userguide/quickstart.rst b/docs/userguide/quickstart.rst
index 75dc302f..7f111dd5 100644
--- a/docs/userguide/quickstart.rst
+++ b/docs/userguide/quickstart.rst
@@ -37,26 +37,45 @@ package your project:
     requires = ["setuptools", "wheel"]
     build-backend = "setuptools.build_meta"
 
-Then, you will need a ``setup.cfg`` to specify your package information,
-such as metadata, contents, dependencies, etc. Here we demonstrate the minimum
+Then, you will need a ``setup.cfg`` or ``setup.py`` to specify your package
+information, such as metadata, contents, dependencies, etc. Here we demonstrate
+the minimum
 
-.. code-block:: ini
+.. tab:: setup.cfg
 
-    [metadata]
-    name = mypackage
-    version = 0.0.1
+    .. code-block:: ini
 
-    [options]
-    packages = mypackage
-    install_requires =
-      requests
-      importlib; python_version == "2.6"
+        [metadata]
+        name = mypackage
+        version = 0.0.1
+
+        [options]
+        packages = mypackage
+        install_requires =
+        requests
+        importlib; python_version == "2.6"
+
+.. tab:: setup.py
+
+    .. code-block:: python
+
+        from setuptools import setup
+
+        setup(
+            name='mypackage"'
+            version='0.0.1',
+            packages=['mypackage'],
+            install_requires=[
+                'requests',
+                'importlib; python_version == "2.6"',
+            ],
+        )
 
 This is what your project would look like::
 
     ~/mypackage/
         pyproject.toml
-        setup.cfg
+        setup.cfg # or setup.py
         mypackage/__init__.py
 
 Then, you need an builder, such as :std:doc:`PyPA build <pypa-build:index>`