From 3dffe711595e037601c5a2b6c850fefc7ae7465f Mon Sep 17 00:00:00 2001 From: Kostya Esmukov Date: Sat, 27 Jul 2019 18:25:40 +0300 Subject: [PATCH] Add `scaraplate-example-template` to docs --- docs/index.rst | 3 +- docs/template.rst | 120 ++++++++++++++++++++++++++++++++++++++- src/scaraplate/rollup.py | 14 +++-- 3 files changed, 130 insertions(+), 7 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index e84de0e..ab20cc4 100644 --- a/docs/index.rst +++ b/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. diff --git a/docs/template.rst b/docs/template.rst index dfbf2dc..7b7c99d 100644 --- a/docs/template.rst +++ b/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: kostya@esmukov.ru + 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: kostya@esmukov.ru + 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': 'kostya@esmukov.ru', + '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 diff --git a/src/scaraplate/rollup.py b/src/scaraplate/rollup.py index 7d43d61..f6051ee 100644 --- a/src/scaraplate/rollup.py +++ b/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)