Add README.rst to example_tomlgen and improve tomlgen_rust documentation

Signed-off-by: Martin Larralde <[email protected]>

Author: Martin Larralde

example_tomlgen/README.rst

@@ -2,4 +2,116 @@
 =================
 
 An example extensions with automatically generated ``Cargo.toml`` manifest
-files.
+files. Simply run ``python setup.py tomlgen_rust`` to generate the following
+files:
+
+* ``Cargo.toml`` for ``hello.english``
+
+.. code-block:: toml
+
+    [package]
+    name = "hello.english"
+    version = "0.1.0"
+    authors = ["Martin Larralde <[email protected]>"]
+    publish = false
+
+    [lib]
+    crate-type = ["cdylib"]
+    name = "hello_english"
+    path = "lib.rs"
+
+    [dependencies]
+    pyo3 = { version = "*", features = ["extension-module"] }
+    english-lint = "*"
+
+
+* ``Cargo.toml`` for ``hello.french``
+
+.. code-block:: toml
+
+    [package]
+    name = "hello.french"
+    version = "0.1.0"
+    authors = ["Martin Larralde <[email protected]>"]
+    publish = false
+
+    [lib]
+    crate-type = ["cdylib"]
+    name = "hello_french"
+    path = "lib.rs"
+
+    [dependencies]
+    pyo3 = { version = "*", features = ["extension-module"] }
+
+
+Metadata
+--------
+
+The package name will be generated from the position of the extension within
+the Python package. The same version is used as the one declared in ``setup.py``
+or ``setup.cfg``.
+
+The authors list is generated after the ``author`` and ``author_email`` options
+from ``setup.py`` / ``setup.cfg``, but can also be overriden using the
+``authors`` key in the ``[tomlgen_rust]`` section of ``setup.cfg``:
+
+.. code-block:: toml
+
+    [tomlgen_rust]
+    authors =
+      Jane Doe <[email protected]>
+      John Doe <[email protected]>
+
+The library name is a slugified variant of the extension package name, to
+avoid name collisions within the build directory.
+
+As a safety, ``publish = false`` is added to the ``[package]`` section
+(you wouldn't publish an automatically generated package, *would you ?!*).
+
+
+Options
+-------
+
+Use ``--force`` (or add ``force = true`` to the ``[tomlgen_rust]`` section of
+``setup.cfg``) to force generating a manifest even when one already exists.
+
+Use ``--create-workspace`` to create a virtual manifest at the root of your
+project (next to the ``setup.py`` file) which registers all of the extensions.
+This way, generic ``cargo`` commands can be run without leaving the root of
+the project.
+
+
+Dependencies
+------------
+
+To specify dependencies for all extensions, add them to the
+``[tomlgen_rust.dependencies]`` section of your setuptools configuration file
+(``setup.cfg``), as you would normally in your ``Cargo.toml`` file. Here is
+probably a good place to add ``pyo3`` as a dependency.
+
+To specify per-extension dependency, create a section for each extension
+(``[tomlgen_rust.dependencies.<DOTTEDPATH>]``, where ``<DOTTEDPATH>`` is the
+complete Python path to the extension (e.g. ``hello.english``). Extension
+specific dependencies are added *after* global dependencies.
+
+*Note that, since all projects are built in the same directory, you can also
+declare all dependencies in the ``[tomlgen_rust.dependencies]``, as they will
+be built only once anyway*.
+
+
+Automatic generation at each build
+----------------------------------
+
+If you intend to regenerate manifests everytime the library is built, you can
+add ``Cargo.toml`` and ``Cargo.lock`` to your ``.gitignore`` file.
+
+Then, make sure ``tomlgen_rust`` is run before ``build_rust`` everytime by
+adding aliases to your ``setup.cfg`` file:
+
+.. code-block:: toml
+
+    [aliases]
+    build_rust = tomlgen_rust -f build_rust
+    clean_rust = tomlgen_rust -f clean_rust
+    build = tomlgen_rust -f build
+    clean = clean_rust -f clean

example_tomlgen/setup.cfg

@@ -1,5 +1,10 @@
 [metadata]
 author_email = "[email protected]"
+description = Example Python/Rust project with automatic Cargo.toml generation
+long-description = file: README.rst
+
+[options]
+zip_safe = false
 
 [tomlgen_rust]
 create_workspace = true
@@ -12,3 +17,6 @@ english-lint = "*"
 
 [aliases]
 build_rust = tomlgen_rust build_rust
+clean_rust = tomlgen_rust clean_rust
+build = tomlgen_rust build
+clean = clean_rust clean

example_tomlgen/setup.py

@@ -1,3 +1,6 @@
+#!/usr/bin/env python
+# coding: utf-8
+
 import setuptools
 import setuptools_rust as rust
 
@@ -13,6 +16,12 @@
         strip=rust.Strip.Debug,
     ),
 
+    # specify setup dependencies
+    setup_requires=[
+        'setuptools',
+        'setuptools_rust',
+    ],
+
     # rust extensions are not zip safe, just like C-extensions.
     zip_safe=False
 )

setuptools_rust/tomlgen.py

@@ -56,8 +56,9 @@ def finalize_options(self):
 
         # Build list of authors
         if self.authors is not None:
+            sep = '\n' if '\n' in self.authors.strip() else ','
             self.authors = "[{}]".format(
-                ", ".join(author.strip() for author in self.authors.split('\n')))
+                ", ".join(author.strip() for author in self.authors.split(sep)))
         else:
             self.authors = '["{} <{}>"]'.format(
                 self.distribution.get_author(),
@@ -139,8 +140,11 @@ def build_workspace_toml(self):
     def iter_dependencies(self, ext=None):
 
         command = self.get_command_name()
+
+        # global dependencies
         sections = ['{}.dependencies'.format(command)]
 
+        # extension-specific dependencies
         if ext is not None:
             sections.append('{}.dependencies.{}'.format(command, ext.name))
 
@@ -194,9 +198,7 @@ def find_rust_extensions(*directories, libfile="lib.rs", **kwargs):
                      └  Cargo.toml
             setup.py
 
-        The only extension can be found in the ``lib`` module:
-
-        .. code-block:: python
+        The only extension can be found in the ``lib`` module::
 
             >>> import setuptools_rust as rust
             >>> for ext in rust.find_rust_extensions("lib"):