====================
 Create the Project
====================


Project Naming
--------------

Obviously the very first step is to come up with a name for your new
app/project.

As already mentioned, this tutorial uses **Poser** for the
(placeholder) project name.  But for the moment, let's pretend the
name is **My Cool App** and walk through the 4 "variations" involved.

When you generate code via cookiecutter (below) you will be asked for
each of these "types" of names.  Here are descriptions and examples
which hopefully show the distinction:

* **project name** - human-friendly display name for the project
  (``My Cool App``)
* **distribution name** - PyPI-friendly name for the release
  (``My-Cool-App`` or ``my-cool-app`` or ``MyCoolApp``)
* **package name** - Python-friendly name which code can import
  (``my_cool_app`` or ``mycoolapp``)
* **repo name** - "slug" name used for source folder and URLs
  (``my-cool-app`` or ``mycoolapp``)


Virtual Environment
-------------------

Now that the name is settled, let's create a Python virtual
environment:

.. code-block:: sh

   python3 -m venv ~/poserenv

From now on all commands will generally be ran within the root folder
of the virtual environment, which should be activated:

.. code-block:: sh

   cd ~/poserenv
   source bin/activate


Cookie Cutter
-------------

We'll be using `cookiecutter`_ to generate starting code for the new
project, so install that:

.. _cookiecutter: https://cookiecutter.readthedocs.io/

.. code-block:: sh

   pip install cookiecutter


Generate Code
-------------

Next we'll invoke the `wuttaweb template`_ for cookiecutter.

.. _wuttaweb template: https://forgejo.wuttaproject.org/wutta/cookiecutter-wuttaweb

You can specify the desired output path via the ``-o <dir>`` argument.
Note that a new folder *underneath* the output folder will be created,
named according to your project.

Using commands below, we'll wind up with output in the ``~/src/poser``
folder.

.. code-block:: sh

   mkdir -p ~/src
   cookiecutter -o ~/src git+https://forgejo.wuttaproject.org/wutta/cookiecutter-wuttaweb

The ``cookiecutter`` command will ask you questions about project
naming etc.  See above for more about the name variations.

When asked about "Continuum data versioning" you probably should say
yes, unless you know you don't want it.  This provides a version
history feature which can be used for any tables you create.


Commit Code
-----------

It's a good idea to commit the fresh project code as-is.  That way
it's clear what was generated vs. what you change going forward.

It may be helpful to add notes to the commit message indicating the
procedure used to generate the code, along with answers given to the
template questions etc.

.. code-block:: sh

   cd ~/src/poser
   git init .
   git add .
   git commit -m "initial code generated via cookiecutter"


Install Package
---------------

Final step here is to install the new Python package into our virtual
environment:

.. code-block:: sh

   pip install -e ~/src/poser