Transfer ad-hoc setup docs to tutorial project

docs/create-project.rst

@@ -0,0 +1,194 @@
+
+.. highlight:: sh
+
+Create a New Project
+====================
+
+Now that you've setup your development environment, you're ready to create a
+new Rattail-based project.
+
+.. todo::
+   link to dev env setup doc here?
+
+Note again that while Rattail is a project in itself, your app is yet another
+project, which is "based" on Rattail but otherwise has a life of its own.  It
+is *not* a "fork" of Rattail but intsead uses Rattail as a library.
+
+Notes About Names
+-----------------
+
+There are some points to be made here, regarding project names.
+
+First point has to do with the "types" of names involved.  Really there are 3:
+
+* "repo" name
+* "project" name
+* "package" name
+
+What we're calling "repo" name here, refers to the so-called "slug" name for
+the repo, e.g. the actual folder name for the repo on disk.
+
+What we're calling "project" name here, refers to the "official" project name,
+e.g. as it might be registered on PyPI or generally referenced in
+documentation, etc.
+
+What we're calling "package" name here, refers to the actual name of the Python
+package contained within the project.
+
+And there technically is a 4th, the "virtualenv" name.  This refers to the
+Python virtual environment you will create, within which you will install your
+project.  This virtualenv name need not be related necessarily, to your project
+name, but in practice it usually would be.  In some cases you may have multiple
+virtualenvs and each must of course get a unique name.
+
+Some examples will surely help.
+
+.. todo::
+   should really have a table instead of lists here?
+
+Example Project: Poser
+
+* repo name: poser
+* project name: Poser
+* package name: poser
+
+Example Project: rattail-tutorial
+
+* repo name: rattail-tutorial
+* project name: rattail-tutorial
+* package name: rattut
+
+Note how the "Poser" name is much more friendly and homogenous as compared to
+the "rattail-tutorial" name, when considering all 3 "types" of names involved.
+Really "rattail-tutorial" is not an example of a good name per se, but it was
+given to this project for other reasons.
+
+This sort of brings us to the second point about names, which is that they
+*should* be "good" generally speaking.  You ideally would want a name more like
+"Poser" in that it's simple and easily recognizable, etc.
+
+.. todo::
+   link to "how to name project" doc
+   (https://rattailproject.org/moin/LilSnippets/ProjectNaming)
+
+Creating the Virtual Environment
+--------------------------------
+
+As mentioned above, the name you give your virtual environment is really up to
+you, and needn't "match" your project name etc.
+
+Let's assume for a moment that you are creating a new project (described next)
+named "Poser" - you likely will want to make a virtualenv named "poser" also::
+
+   mkvirtualenv --python=/usr/bin/python3 poser
+    
+Note that you should specify the path to your Python 3 executable, to avoid
+using the "default" which is likely still Python 2 at this time.
+
+For the sake of this tutorial, we'll be using the "rattut" env name::
+
+   mkvirtualenv --python=/usr/bin/python3 rattut
+    
+Please note that pretty much all subsequent commands shown, will assume your
+virtual environment (regardless what you named it) is currently *active*.  It
+should be obvious when a virtualenv is active, since it should modify the shell
+prompt to reflect that.
+
+If you do need to deactivate your current virtualenv, you can do that with::
+
+   deactivate
+
+And then to re-activate your virtualenv you do::
+
+   workon rattut
+
+Or maybe ``workon poser`` etc., whatever named env you want to activate.
+
+Installing Rattail Packages
+---------------------------
+
+If you're just wanting to run the rattail-tutorial app instead of creating your
+own project, you can skip this step.
+
+But in this tutorial we're showing how to do it all, and so before we can
+create the tutorial project itself we must first install some Rattail packages
+to our virtual environment.  Well really there's just one (Tailbone) which is
+needed because it contains the "rattail" scaffold, and also it depends on other
+packages (namely, Pyramid) which are needed for the scaffold feature::
+
+   pip install Tailbone
+
+Creating the Project
+--------------------
+
+Again if you're just wanting to run the rattail-tutorial app you can skip this
+step.
+
+First of all you should change directory to wherever you want to create the
+actual project source folder.  Rattail docs will generally assume that's at
+``~/src`` in which case you should do something like::
+
+   mkdir -p ~/src
+   cd ~/src
+
+Remember all that talk about names, up above?  Well now you will be specifying
+a *single* name when creating your project.  In practice the name you provide:
+
+* should be lower-cased
+* will be used as-is for the "repo" name
+* will be capitalized (and weird chars replaced) to obtain "project" name
+* will be used as-is for the "package" name, except weird chars replaced by "_"
+
+Got all that straight?  If not, no worries, just try this a few times and see
+what you end up with.  Assuming you did want the project name "Poser" you would
+run the command::
+
+   pcreate -s rattail poser
+
+This will use the "scaffold" (basically, set of templates) which is named
+"rattail" to generate a new folder containing files which define a new "Poser"
+project, within the "poser" folder under current directory.
+
+Since this tutorial project is named "rattail-tutorial" and there's no possible
+way for the scaffold to know that we want to use "rattut" as the Python package
+name, we had to simply "pick our poison" when generating the initial tutorial
+project.  In other words we did::
+
+   pcreate -s rattail rattail-tutorial
+
+Note that per the above rules, what the scaffold assumed by default was:
+
+* repo name was "rattail-tutorial"
+* project name was "Rattail_tutorial"
+* package name was "rattail_tutorial"
+
+We'll clean that up a bit shortly, but first let's start Git tracking.
+
+Making a Git Repo
+-----------------
+
+We never want to start a new project without also starting a proper Git repo
+for it.  We will want to be able to ``git push`` the code to a central
+location, e.g. GitHub or similar.
+
+Change directory to your new project's source repo folder and then initialize::
+
+   cd ~/src/rattail-tutorial
+   git init
+
+We also want our first commit to include all the generated code so far::
+
+   git add .
+   git commit -m "Initial content as generated from project scaffold"
+
+Now we'll establish our upstream and do our first push.  How exactly you go
+about this may vary, and certainly the commands shown here will *not* work for
+you as-is, since your "origin" at least will need to be different::
+
+   git remote add origin git@rattailproject.org:/srv/git/rattail-tutorial.git
+   git push --set-upstream origin master
+
+And finally, at least in the case of this tutorial project, we wanted to go
+through and clean up some of the generated names, as well as assign authorship
+and project description etc. within the ``setup.py`` file.  (Then commit those
+changes and do another push, so we again have "clean" git status.)