diff --git a/docs/source/how-to/how-to-how-to.rst b/docs/source/how-to/how-to-how-to.rst index 23b7cfe..6b0c5fd 100644 --- a/docs/source/how-to/how-to-how-to.rst +++ b/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. diff --git a/docs/source/how-to/how-to-quickstart.rst b/docs/source/how-to/how-to-quickstart.rst new file mode 100644 index 0000000..d56dfc8 --- /dev/null +++ b/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` 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:\> \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` 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 + + +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` for more information. + + + +.. _cookiecutter: https://cookiecutter.readthedocs.io/en/1.7.2/README.html diff --git a/docs/source/how-to/index-how-to.rst b/docs/source/how-to/index-how-to.rst index d62fad2..9fcf21c 100644 --- a/docs/source/how-to/index-how-to.rst +++ b/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 diff --git a/docs/source/index.rst b/docs/source/index.rst index 8f25714..eff31c4 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/reference/index-reference.rst b/docs/source/reference/index-reference.rst new file mode 100644 index 0000000..589cf6f --- /dev/null +++ b/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 diff --git a/docs/source/prompts.rst b/docs/source/reference/reference-project-inputs.rst similarity index 97% rename from docs/source/prompts.rst rename to docs/source/reference/reference-project-inputs.rst index a591b41..dae3098 100644 --- a/docs/source/prompts.rst +++ b/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.