Add scaraplate-example-template to docs

docs/index.rst

@@ -81,7 +81,8 @@ Installation:
 
 To get started with scaraplate, you need to:
 
-1. Prepare a template (see :doc:`template`).
+1. Prepare a template (see :doc:`template` and specifically
+   :ref:`scaraplate_example_template`).
 2. Roll it up on your projects.
 
 

docs/template.rst

@@ -1,4 +1,4 @@
-Scaraplate template
+Scaraplate Template
 ===================
 
 Scaraplate uses cookiecutter under the hood, so the scaraplate template
@@ -37,6 +37,124 @@ directories (i.e. the template git repo must be cloned manually,
 scaraplate doesn't support retrieving templates from git remote directly).
 
 
+.. _scaraplate_example_template:
+
+Scaraplate Example Template
+---------------------------
+
+We maintain an example template for a new Python project here:
+https://github.com/rambler-digital-solutions/scaraplate-example-template
+
+You may use it as a starting point for creating your own scaraplate template.
+Of course it doesn't have to be for a Python project: the cookiecutter
+template might be for anything. A Python project is just an example.
+
+Creating a new project from the template
+++++++++++++++++++++++++++++++++++++++++
+
+::
+
+    $ git clone https://github.com/rambler-digital-solutions/scaraplate-example-template.git
+    $ scaraplate rollup ./scaraplate-example-template ./myproject
+    `myproject1/.scaraplate.conf` file doesn't exist, continuing with an empty context...
+    `project_dest` must equal to "myproject"
+    project_dest [myproject]:
+    project_monorepo_name []:
+    python_package [myproject]:
+    metadata_name [myproject]:
+    metadata_author: Kostya Esmukov
+    metadata_author_email: [email protected]
+    metadata_description: My example project
+    metadata_long_description [file: README.md]:
+    metadata_url [https://github.com/rambler-digital-solutions/myproject]:
+    coverage_fail_under [100]: 90
+    mypy_enabled [1]:
+    Done!
+    $ tree -a myproject
+    myproject
+    ├── .editorconfig
+    ├── .gitignore
+    ├── .scaraplate.conf
+    ├── MANIFEST.in
+    ├── Makefile
+    ├── README.md
+    ├── mypy.ini
+    ├── setup.cfg
+    ├── setup.py
+    ├── src
+    │   └── myproject
+    │       └── __init__.py
+    └── tests
+        ├── __init__.py
+        └── test_metadata.py
+
+    3 directories, 12 files
+
+The example template also contains a ``project_monorepo_name`` variable
+which simplifies creating subprojects in monorepos (e.g. a single git
+repository for multiple projects). In this case scaraplate should be
+applied to the inner projects:
+
+::
+
+    $ scaraplate rollup ./scaraplate-example-template ./mymonorepo/innerproject
+    `mymonorepo/innerproject/.scaraplate.conf` file doesn't exist, continuing with an empty context...
+    `project_dest` must equal to "innerproject"
+    project_dest [innerproject]:
+    project_monorepo_name []: mymonorepo
+    python_package [mymonorepo_innerproject]:
+    metadata_name [mymonorepo-innerproject]:
+    metadata_author: Kostya Esmukov
+    metadata_author_email: [email protected]
+    metadata_description: My example project in a monorepo
+    metadata_long_description [file: README.md]:
+    metadata_url [https://github.com/rambler-digital-solutions/mymonorepo]:
+    coverage_fail_under [100]: 90
+    mypy_enabled [1]:
+    Done!
+    $ tree -a mymonorepo
+    mymonorepo
+    └── innerproject
+        ├── .editorconfig
+        ├── .gitignore
+        ├── .scaraplate.conf
+        ├── MANIFEST.in
+        ├── Makefile
+        ├── README.md
+        ├── mypy.ini
+        ├── setup.cfg
+        ├── setup.py
+        ├── src
+        │   └── mymonorepo_innerproject
+        │       └── __init__.py
+        └── tests
+            ├── __init__.py
+            └── test_metadata.py
+
+    4 directories, 12 files
+
+Updating a project from the template
+++++++++++++++++++++++++++++++++++++
+
+::
+
+    $ scaraplate rollup ./scaraplate-example-template ./myproject --no-input
+    Continuing with the following context from the `myproject/.scaraplate.conf` file:
+    {'_template': 'scaraplate-example-template',
+     'coverage_fail_under': '90',
+     'metadata_author': 'Kostya Esmukov',
+     'metadata_author_email': '[email protected]',
+     'metadata_description': 'My example project',
+     'metadata_long_description': 'file: README.md',
+     'metadata_name': 'myproject',
+     'metadata_url': 'https://github.com/rambler-digital-solutions/myproject',
+     'mypy_enabled': '1',
+     'project_dest': 'myproject',
+     'project_monorepo_name': '',
+     'python_package': 'myproject'}
+    Done!
+
+
 .. _cookiecutter_context_types:
 
 Cookiecutter context types

src/scaraplate/rollup.py

@@ -63,7 +63,7 @@ def rollup(
 
         with with_cwd(template_root_path):
             # Cookiecutter preserves its template values to
-            # setup.cfg (this is specified in the template).
+            # .scaraplate.conf/setup.cfg (this is specified in the template).
             #
             # These values contain a `_template` key, which points to
             # the template just like it was passed to cookiecutter
@@ -139,17 +139,21 @@ def get_target_project_cookiecutter_context(
     try:
         context = cookiecutter_context.read()
     except FileNotFoundError:
-        click.echo("setup.cfg doesn't exist, continuing with an empty context")
+        click.echo(
+            f"`{cookiecutter_context}` file doesn't exist, "
+            f"continuing with an empty context..."
+        )
         return {}
     else:
         if context:
             click.echo(
-                f"Continuing with the following context:\n{pprint.pformat(context)}"
+                f"Continuing with the following context from "
+                f"the `{cookiecutter_context}` file:\n{pprint.pformat(context)}"
             )
         else:
             click.echo(
-                f"No context found in the {cookiecutter_context}, "
-                f"continuing with an empty one"
+                f"No context found in the `{cookiecutter_context}` file, "
+                f"continuing with an empty one..."
             )
         return dict(context)