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'