docs(how-to): Add several how-tos #82 #149 (#152)

Add Quickstart.
Ad How-to How-to

closes #82
closes #149

docs/source/how-to/how-to-how-to.rst

@@ -10,30 +10,35 @@ How-To How-To
 =============
 
 
-What
-----
+What is a How-to
+----------------
 
 Its a Recipe
 
 Recipes are an excellent model for writing a how-to guide.
 
-Recipes clearly define the goal by following it, and they address a specific question: How do I make it?
+Recipes clearly define the goal by following it, and they address a specific
+question: How do I make it?
 
-Why
----
+Why: adds noise
+--------------
 
-Explanations aren't necessary when following a how-to guide. Adding descriptions is adding noise on the way to the goal.
+Explanations aren't necessary when following a how-to guide. Adding
+descriptions is adding noise on the way to the goal.
 
-How
----
+How: the steps to take
+----------------------
 
 How-to guides contain a sequence of actions much like a tutorial.
 
-They differ in a sense; a tutorial mentions that "We are using HTTPS" because it is very secure, whereas a How-to guide digs deeper into HTTPS, that is, it shows you how to do a specific action or configuration with HTTPS.
+They differ in a sense; a tutorial mentions that "We are using HTTPS" because
+it is very secure, whereas a How-to guide digs deeper into HTTPS, that is, it
+shows you how to do a specific action or configuration with HTTPS.
 
-How-to guides don't need the repeatability of a tutorial, but they should be reliable.
+How-to guides don't need the repeatability of a tutorial, but they should be
+reliable.
 
-When
-----
+When to write one
+-----------------
 
 The goal of a how-to is to solve a problem or complete an unfamiliar task.

docs/source/how-to/how-to-quickstart.rst

@@ -0,0 +1,190 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: how-to-quickstart ; Index
+
+.. _how-to-quickstart:
+==========
+Quickstart
+==========
+
+See :ref:`Reference Project Inputs<project-inputs>` for all information
+collected to create a new cookiecutter-py3-package.
+
+Create a GitHub Repository
+--------------------------
+
+Your new GitHub repository information is required to generate
+your cookiecutter-py3-package in these steps.
+
+project_name
+~~~~~~~~~~~~
+
+The name of your new cookiecutter-py3-package,  used in the documentation,
+so spaces and any characters are acceptable here.
+
+Typically the repository name in sentence form.
+
+project_short_description
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+A  sentence describes your cookiecutter-py3-package.
+
+Typically the repository description.
+
+
+Create Virtual Environment
+--------------------------
+
+**Select the tab for your preferred Operating System.**
+
+.. tab:: Linux
+
+    .. code-block:: bash
+        :caption: **bash/zsh**
+
+        python3 -m venv venv
+        source venv/bin/acivate
+        pip install --upgrade pip
+
+    You will have a folder structure similar to this.
+
+    .. code-block:: bash
+
+            packages
+            └── venv
+
+
+.. tab:: macOS
+
+
+    .. code-block:: bash
+        :caption: **bash/zsh**
+
+        python3 -m venv venv
+        source venv/bin/acivate
+        pip install --upgrade pip
+
+    You will have a folder structure similar to this.
+
+    .. code-block:: bash
+
+            packages
+            └── venv
+
+.. tab:: Windows
+
+    If you have installed Python in your PATH and PATHEXT.
+
+    .. code-block:: bash
+        :caption: **cmd/PowerShell**
+
+        python3 -m venv venv
+
+        C:\> venv\Scripts\activate.bat  # cmd.exe
+        PS C:\> venv\Scripts\Activate.ps1 # Powershell
+
+        pip install --upgrade pip
+
+    Otherwise use
+
+    .. code-block:: bash
+        :caption: **cmd/PowerShell**
+
+        c:\>c:\Python36\python -m venv c:\path\to\packages\my_env
+        PS C:\> <venv>\Scripts\Activate.ps1
+
+        C:\> venv\Scripts\activate.bat  # cmd.exe
+        PS C:\> venv\Scripts\Activate.ps1 # Powershell
+
+        pip install --upgrade pip
+
+    You will have a folder structure similar to this.
+
+    .. code-block:: bash
+
+            packages
+            └── venv
+
+.. _quick_install-cookiecutter:
+Install Cookiecutter
+--------------------
+
+Firstly it's advisable to upgrade pip using the following command.
+
+.. code-block:: bash
+    :caption: **Linux, macOS and Windows**
+
+    pip install --upgrade pip
+
+You will see something like this in your CLI.
+
+.. code-block:: cmd
+
+    Requirement already satisfied: pip in ./my_env/lib/python3.9/site-packages (21.2.3)
+    Collecting pip
+     Using cached pip-21.2.4-py3-none-any.whl (1.6 MB)
+    Installing collected packages: pip
+      Attempting uninstall: pip
+        Found existing installation: pip 21.2.3
+        Uninstalling pip-21.2.3:
+          Successfully uninstalled pip-21.2.3
+    Successfully installed pip-21.2.4
+
+Install cookiecutter_ into your virtual environment.
+
+.. code-block:: bash
+    :caption: **Linux, macOS and Windows**
+
+    pip install cookiecutter
+
+Start Cookiecutter-Py3-Package
+------------------------------
+
+In your packages folder, use the following command.
+
+.. code-block:: bash
+    :caption: **Linux, macOS and Windows**
+
+    cookiecutter https://github.com/imAsparky/cookiecutter-py3-package
+
+Cookiecutter will ask questions to set your package up.
+If you're unsure or don't know what to enter, stick with the defaults.
+
+See :ref:`Reference-Inputs<project-inputs>` for more details about the
+cookiecutter-py3- project options.
+
+.. code-block:: bash
+
+    packages
+        ├── venv
+        └── my-new-package
+
+
+Install Dependencies
+--------------------
+
+
+Change into your project directory.
+
+
+.. code-block:: bash
+
+    cd <your my-new-package folder>
+
+
+Install dependencies.
+
+.. code-block:: bash
+
+    pip install -r requirements_dev.txt
+
+
+Congratulations, you have created your new Python Package.
+
+Depending on your chosen options, there are several ways to proceed with
+pushing to GitHub.  If you are unsure, see our
+:ref:`git push tutorial<create-first-git-push>` for more information.
+
+
+
+.. _cookiecutter: https://cookiecutter.readthedocs.io/en/1.7.2/README.html

docs/source/how-to/index-how-to.rst

@@ -20,3 +20,4 @@ This index is a document framework placeholder for new How To's.
    :titlesonly:
 
    how-to-how-to
+   how-to-quickstart

docs/source/index.rst

@@ -21,7 +21,6 @@ See a list of the Original and new In Progress Documents below.
 
    readme
    tutorial
-   prompts
    pypi_release_checklist
    console_script_setup
    troubleshooting
@@ -38,10 +37,16 @@ See a list of the Original and new In Progress Documents below.
 
 .. toctree::
    :titlesonly:
-   :caption: How-To's Placeholder:
 
    how-to/index-how-to
 
+|
+|
+
+.. toctree::
+   :titlesonly:
+
+   reference/index-reference
 
 
 Changelog

docs/source/reference/index-reference.rst

@@ -0,0 +1,17 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: reference-index ; Index
+
+
+.. _reference-index:
+=========
+Reference
+=========
+
+See below for a list of reference material for Django Cookiecutter.
+
+
+.. toctree::
+   :titlesonly:
+
+   reference-project-inputs

docs/source/prompts.rst → docs/source/reference/reference-project-inputs.rst

@@ -1,13 +1,14 @@
 .. include:: /extras.rst.txt
 .. highlight:: rst
-.. index:: cookie-prom-pkg ; Index
+.. index:: py3-project-inputs ; Index
 
-.. _cookie_prompts:
-=======
-Prompts
-=======
+.. _project-inputs:
+==================
+New Project Inputs
+==================
 
-*Copyright 2015, Audrey Roy Greenfeld*
+
+*Portions are Copyright 2015, Audrey Roy Greenfeld*
 
 When you create a package, you are prompted to enter these values.