diff --git a/doc-source/comparison.py b/doc-source/comparison.py
new file mode 100644
index 0000000..730e70a
--- /dev/null
+++ b/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)
diff --git a/doc-source/comparison.rst b/doc-source/comparison.rst
new file mode 100644
index 0000000..569c6e8
--- /dev/null
+++ b/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 `_
+.. [3] In development :github:pull:`393 `
+.. [4] As of :github:pull:`260 `
diff --git a/doc-source/comparison.toml b/doc-source/comparison.toml
new file mode 100644
index 0000000..0e8817d
--- /dev/null
+++ b/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 = "?"
diff --git a/doc-source/index.rst b/doc-source/index.rst
index c1952f5..d564f00 100644
--- a/doc-source/index.rst
+++ b/doc-source/index.rst
@@ -201,6 +201,7 @@ Contents
configuration
cli
+ comparison
Source
.. toctree::
diff --git a/pyproject.toml b/pyproject.toml
index 4d6e07a..e1b6853 100644
--- a/pyproject.toml
+++ b/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"
diff --git a/repo_helper.yml b/repo_helper.yml
index 1fdda4f..2d4f53a 100644
--- a/repo_helper.yml
+++ b/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'