Add a comparison table with different backends.

doc-source/comparison.py

@@ -0,0 +1,80 @@
+# 3rd party
+import dom_toml
+from docutils import nodes
+from docutils.parsers.rst import directives
+from docutils.statemachine import StringList
+from domdf_python_tools import stringlist
+from domdf_python_tools.paths import PathPlus
+from sphinx.application import Sphinx
+from sphinx.util.docutils import SphinxDirective
+from sphinx_toolbox.utils import Purger
+
+purger = Purger("all_comparison_nodes")
+
+
+class ComparisonDirective(SphinxDirective):
+
+	option_spec = {"widths": directives.unchanged_required}
+
+	def run(self):
+		config = dom_toml.load(PathPlus(self.env.srcdir) / "comparison.toml")
+
+		table_source = stringlist.StringList()
+		table_source.append(".. list-table:: Comparison of Tools")
+
+		widths = self.options.get("widths", "15 10 10 10 10 15 10 12 12")
+
+		with table_source.with_indent("    ", 1):
+			table_source.extend([
+					f":widths: {widths}",
+					":header-rows: 1",
+					":stub-columns: 1",
+					'',
+					"* - Tool",
+					"  - :pep:`517` support",
+					"  - :pep:`621` support",
+					"  - ``src`` layout support",
+					"  - Builds C Extensions",
+					"  - Can Install Project",
+					"  - Upload to PyPI",
+					"  - First Release",
+					"  - Python Versions",
+					])
+
+			for name, tool in config.items():
+				if "link" in tool:
+					table_source.append(f"* - `{name} <{tool['link']}>`_")
+				else:
+					table_source.append(f"* - {name}")
+
+				for key in [
+						"supports_517",
+						"supports_621",
+						"src_layout",
+						"build_extensions",
+						"install",
+						"upload",
+						]:
+
+					value = tool.get(key, False)
+
+					if value is True:
+						table_source.append("  - Yes")
+					elif value is False:
+						table_source.append("  - No")
+					else:
+						table_source.append(f"  - {value}")
+
+				table_source.append(f"  - {tool.get('released', '')}")
+				table_source.append(f"  - {tool.get('python_versions', '')}")
+
+		node = nodes.paragraph()
+		self.state.nested_parse(StringList(table_source), self.content_offset, node)
+		purger.add_node(self.env, node, node, self.lineno)
+
+		return [node]
+
+
+def setup(app: Sphinx):
+	app.add_directive("project-comparison", ComparisonDirective)
+	app.connect("env-purge-doc", purger.purge_nodes)

doc-source/comparison.rst

@@ -0,0 +1,14 @@
+===========
+Why Whey?
+===========
+
+Why would you pick whey over its contemporaries, and why might another tool be better?
+
+
+.. project-comparison::
+
+
+.. [1] Use of ``setup.py install`` is discouraged
+.. [2] Bundled with `Python 1.6 <https://www.python.org/download/releases/1.6/>`_
+.. [3] In development :github:pull:`393 <takluyver/flit>`
+.. [4] As of :github:pull:`260 <takluyver/flit>`

doc-source/comparison.toml

@@ -0,0 +1,57 @@
+[Whey]
+supports_517 = true
+supports_621 = true
+install = "No -- Use pip"
+upload = "No -- Use twine"
+released = "Feb 2021"
+src_layout = true
+python_versions = ">=3.6"
+
+[Distutils]
+link = "https://docs.python.org/3/library/distutils.html"
+build_extensions = true
+upload = true
+src_layout = "?"
+install = "Yes [1]_"
+released = "2000 [2]_"
+
+[Setuptools]
+link = "https://setuptools.readthedocs.io/en/latest/"
+supports_517 = true
+build_extensions = true
+upload = "Maybe"
+install = "Yes [1]_"
+released = "May 2006"
+python_versions = ">=3.6"
+src_layout = true
+
+[Flit]
+link = "https://flit.readthedocs.io/en/latest/index.html"
+supports_517 = true
+supports_621 = "Yes [3]_"
+src_layout = "Yes [4]_"
+install = true
+upload = true
+released = "March 2015"
+python_versions = ">=3.5"
+
+[Poetry]
+link = "https://python-poetry.org/"
+supports_517 = true
+supports_621 = false
+install = true
+upload = true
+released = "Feb 2018"
+python_versions = ">=2.7 or >=3.5"
+src_layout = "?"
+
+[Enscons]
+link = "https://github.com/dholth/enscons"
+supports_517 = true
+supports_621 = true
+build_extensions = true
+install = "?"
+upload = "?"
+released = "June 2016"
+python_versions = "2 and 3"
+src_layout = "?"

doc-source/index.rst

@@ -201,6 +201,7 @@ Contents
 
 	configuration
 	cli
+	comparison
 	Source
 
 .. toctree::

pyproject.toml

@@ -70,6 +70,7 @@ extensions = [
     "sphinx_toolbox_experimental.needspace",
     "sphinx_toolbox_experimental.peps",
     "sphinx_toolbox_experimental.toml",
+    "comparison",
 ]
 sphinxemoji_style = "twemoji"
 gitstamp_fmt = "%d %b %Y"

repo_helper.yml

@@ -48,6 +48,7 @@ extra_sphinx_extensions:
  - sphinx_toolbox_experimental.needspace
  - sphinx_toolbox_experimental.peps
  - sphinx_toolbox_experimental.toml
+ - comparison
 
 classifiers:
  - 'Development Status :: 3 - Alpha'