From 8a493bfc44a8bdb59a882190535a2e193642bc30 Mon Sep 17 00:00:00 2001 From: f-osorio Date: Wed, 11 Sep 2019 10:42:23 +0200 Subject: [PATCH] [#4799] Update extension tutorial for cookiecutter Replace mentions of `paster create` with `cookiecutter`. Not sure the final location for the cookiecutter templates, the instructions for how to get it has a placeholder "https://github.com//.git" --- doc/extensions/tutorial.rst | 36 +++++++++++++++++++++++------------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/doc/extensions/tutorial.rst b/doc/extensions/tutorial.rst index 34685abec90..1c6d7ee017e 100644 --- a/doc/extensions/tutorial.rst +++ b/doc/extensions/tutorial.rst @@ -44,14 +44,20 @@ Creating a new extension CKAN config file to activate the extension's features. -You can use the ``paster create`` command to create an "empty" extension from +You can use ``cookiecutter`` command to create an "empty" extension from a template. First, activate your CKAN virtual environment: .. parsed-literal:: |activate| -When you run the ``paster create`` command, your new extension's directory will +Install the ``cookiecutter`` python module: + +.. parsed-literal:: + + pip install cookiecutter + +When you run ``cookiecutter``, your new extension's directory will be created in the current working directory by default (you can override this with the ``-o`` option), so change to the directory that you want your extension to be created in. Usually you'll want to track your extension code @@ -65,18 +71,20 @@ contains the CKAN git repo. Let's use the parent directory instead: Now run the ``paster create`` command to create your extension:: - paster --plugin=ckan create -t ckanext ckanext-iauthfunctions - -.. note:: + cookiecutter https://github.com//.git - The last argument to the ``paster create`` command - (``ckanext-iauthfunctions`` in this example) is the name for your next - extension. CKAN extension names *have* to begin with ``ckanext-``. - -The command will ask you to answer a few questions. The answers you give will +The command will present a few prompts. The information you give will end up in your extension's ``setup.py`` file (where you can edit them later if you want). +.. note:: + + The first prompt is for is the name of your next + extension. CKAN extension names *have* to begin with ``ckanext-``. This + tutorial uses the project name ``ckanext-iauthfunctions``. + The prompts for ``project_shortname`` and ``plugin_class_name`` can be + ignored. They will be filled in automatically. + Once this command has completed, your new CKAN extension's project directory will have been created and will contain a few directories and files to get you started:: @@ -111,8 +119,9 @@ Creating a plugin class extension's features. -Now create the file ``ckanext-iauthfunctions/ckanext/iauthfunctions/plugin.py`` -with the following contents: +``cookiecutter`` should have created the following file file +``ckanext-iauthfunctions/ckanext/iauthfunctions/plugin.py``. +Edit it to match the following: .. literalinclude:: ../../ckanext/example_iauthfunctions/plugin_v1.py @@ -132,12 +141,13 @@ in this example, that inherits from CKAN's Adding the plugin to ``setup.py`` ================================= -Now let's add our class to the ``entry_points`` in ``setup.py``. This +Now let's add our class to the ``entry_points`` in ``setup.py``. This identifies the plugin class to CKAN once the extension is installed in CKAN's virtualenv, and associates a plugin name with the class. Edit ``ckanext-iauthfunctions/setup.py`` and add a line to the ``entry_points`` section like this:: + entry_points=''' [ckan.plugins] example_iauthfunctions=ckanext.iauthfunctions.plugin:ExampleIAuthFunctionsPlugin