docs(Diataxis): Add tutes & how-to framework #81 (#98)

* All as per the Project: Improve User experience for the cookiecutter-py3-package documentation. * Tutorials folder with tutorial's files created. * How-To folder with index and How-to How-to created * Old docs and indexes were re-organised, making them available while all the new documents are being written. closes #81
imAsparky · Sep 16, 2021 · 322ac5b · 322ac5b
1 parent f83d972
commit 322ac5b
Show file tree

Hide file tree

Showing 27 changed files with 554 additions and 53 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -3,8 +3,22 @@
 <!--next-version-placeholder-->
 
 ## v0.6.3 (2021-09-16)
+
+### Fix
+
+-   **CHANGELOG:** Auto-generate for repo disabled #94 ([#97](https://github.com/imAsparky/cookiecutter-py3-package/issues/97)) ([`f3f6f9c`](https://github.com/imAsparky/cookiecutter-py3-package/commit/f3f6f9cfcce2375f580a089fa3319ace9108dbeb))
+
+## v0.6.2 (2021-09-16)
+
 ### Fix
-* **CHANGELOG:** Auto-generate for repo disabled #94 ([#97](https://github.com/imAsparky/cookiecutter-py3-package/issues/97)) ([`f3f6f9c`](https://github.com/imAsparky/cookiecutter-py3-package/commit/f3f6f9cfcce2375f580a089fa3319ace9108dbeb))
+
+-   **git** Package git url source updated #95 ([#95](https://github.com/imAsparky/cookiecutter-py3-package/issues/95)) ([`1aa3010`](https://github.com/imAsparky/cookiecutter-py3-package/commit/1aa3010a6765ac5f385d23bd464723ae357fa15e))
+
+## v0.6.1 (2021-09-16)
+
+### Fix
+
+-   **deps** Update pkge requirements_dev.txt #91 ([#91](https://github.com/imAsparky/cookiecutter-py3-package/issues/91)) ([`c7f2eeb`](https://github.com/imAsparky/cookiecutter-py3-package/commit/c7f2eebaec21bd3fc1ea6e52dedb05738748a350))
 
 ## [v0.6.0](https://github.com/imAsparky/cookiecutter-py3-package/releases/tag/v0.6.0) - 2021-09-15 07:10:13
 

diff --git a/README.rst b/README.rst
@@ -17,8 +17,8 @@
 
 **Checkout the** Projects_ **page to see what is planned.**
 
-**We are aiming for your new package to use a Continuous Delivery workflow,
-keeping it automated and straightforward.**
+**We are aiming for your new package to be an automated Continuous Delivery
+workflow experience.**
 
 .. .. image:: https://pyup.io/repos/github/audreyfeldroy/cookiecutter-pypackage/shield.svg
 ..     :target: https://pyup.io/repos/github/audreyfeldroy/cookiecutter-pypackage/
@@ -32,6 +32,14 @@ keeping it automated and straightforward.**
    :alt: Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.
    :target: https://www.repostatus.org/#wip
 
+.. image:: http://isitmaintained.com/badge/resolution/imAsparky/cookiecutter-py3-package.svg
+   :alt: Project is Maintained
+   :target: https://isitmaintained.com/project/imAsparky/cookiecutter-py3-package
+
+.. image:: http://isitmaintained.com/badge/open/imAsparky/cookiecutter-py3-package.svg
+   :alt: Project Open Issues
+   :target: https://isitmaintained.com/project/imAsparky/cookiecutter-py3-package
+
 .. image:: https://app.codacy.com/project/badge/Grade/4c115acc2b3d4d13b998cdcbdb3cea64
     :target: https://www.codacy.com/gh/imAsparky/cookiecutter-py3-package/dashboard?utm_source=github.com&amp;utm_medium=referral&amp;utm_content=imAsparky/cookiecutter-py3-package&amp;utm_campaign=Badge_Grade
     :alt: Code Quality
@@ -45,50 +53,46 @@ keeping it automated and straightforward.**
     :target: https://cookiecutter-py3-package.readthedocs.io/en/latest/?badge=latest
     :alt: Documentation Status
 
-Cookiecutter_ template for a Python package.
+A Cookiecutter_ template for a Python package.
 
 * GitHub repo: https://github.com/imAsparky/cookiecutter-py3-package/
 * Documentation: https://cookiecutter-py3-package.readthedocs.io/
 * Free software: BSD license
 
 
-**Notable changes from the Original project so far.**
-
-#. Links from the original fork have been updated to point to this repository.
-#. Support for Travis has been removed.
-#. Stale "Similar Cookiecutter Templates" have been removed.
-#. `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_
-   specification custom commit message are now built into the
-   cookiecutter-p3-package project.
-#. Choose to use a `Conventional Commits <https://www.conventionalcommits.org/en/v1.0.0/>`_
-   specification custom commits message in your built package.
-#. Added an optional GitHub action to generate a package CHANGELOG automatically.
-#. Added an optional GitHub action to run your tox package test suite when a
-   pull request to the main branch starts.
-#. Tox configuration for your package now includes an OS and Python test matrix.
-   OS includes Linux, macOS and Windows. Python 3.6 - 3.9.
-#. Added an optional GitHub action to automatically update semantic version and
-   publish assets to your package repository when a pull request merge is
-   closed or manually.
-#. Semantic versioning and publishing are also available locally, bypassing
-   the need for a GitHub action if that is your preferred workflow.
-#. Added optional GitHub custom issue templates. The four custom issue templates
-   prompt users to help provide enough information in a templated format for
-   each issue type.
-
 Features
 --------
 
-* Sphinx_ docs: Documentation ready for generation with, for example, `Read the Docs`_.
-* Auto-release to PyPI_ when you push a new tag to main (optional). Coming soon.
-* Use commit tags to release to Test-PyPi_. Coming soon.
-* Command line interface using Click (optional).
+#. Choose to use a Conventional-Commits_ specification custom commits message
+   in your built package.
+#. An optional GitHub action to automatically update semantic version and
+   publish assets to your package repository when a pull request merge is
+   closed or manually.
+#. Manual semantic versioning and publishing are also available locally,
+   bypassing the need for a GitHub action if that is your preferred workflow.
+#. An optional GitHub action to generate a package CHANGELOG automatically if
+   you choose to version and publish your package manually.
+#. An optional GitHub action to run your Tox_ package test suite when a
+   pull request to the main branch starts.
+#. Tox_ configuration for your package includes an OS and Python test matrix.
+   OS includes Linux, macOS and Windows. Python 3.6 - 3.9.
+#. An optional suite of custom GitHub issue templates. The four custom issue
+   templates prompt users to help provide enough information in a templated
+   format for each issue type.
+#. Documentation is in the process of being refreshed and organised into the
+   Diataxis_ documentation framework.
+#. Sphinx_ docs: Documentation ready for generation with, for example, `Read the Docs`_.
+#. Auto-release to PyPI_ when you push a new tag to main (optional). Coming soon.
+#. Use commit tags to release to Test-PyPi_. Coming soon.
+#. An optional Command line interface using Click or Argparse.
 
 .. _Cookiecutter: https://github.com/cookiecutter/cookiecutter
 .. _cookiecutter-pypackage: https://github.com/audreyfeldroy/cookiecutter-pypackage
 .. _Projects: https://github.com/imAsparky/cookiecutter-py3-package/projects
 .. _CHANGELOG: https://github.com/imAsparky/cookiecutter-py3-package/blob/main/CHANGELOG.md
 .. _Test-PyPi: https://test.pypi.org/
+.. _Conventional-Commits:  https://www.conventionalcommits.org/en/v1.0.0/
+.. _Diataxis: https://diataxis.fr/
 
 Quickstart
 ----------

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -25,8 +25,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "cookiecutter-py3-package"
-copyright = "2015, Audrey Roy Greenfeld"
-author = "Audrey Roy Greenfeld"
+copyright = "2021, Mark Sevelj"
+author = "Mark Sevelj"
 
 
 # The short X.Y version.

diff --git a/docs/source/console_script_setup.rst b/docs/source/console_script_setup.rst
@@ -2,6 +2,8 @@
 Console Script Setup
 ====================
 
+*Copyright 2015, Audrey Roy Greenfeld*
+
 Optionally, your package can include a console script using Click or argparse
 (Python 3.2+).
 

diff --git a/docs/source/extras.rst.txt b/docs/source/extras.rst.txt
@@ -0,0 +1,24 @@
+
+..  Every reST source file in this project must include the 'extras.rst.txt' file, which provides some extra formatting options.
+.. 'extras.rst.txt'  can be found at
+  https://github.com/imAsparky/junction-box/tree/main/docs/source/extras.rst.txt
+
+.. ----------
+.. text roles
+.. ----------
+.. role:: emph(emphasis)
+.. role:: html(code)
+.. role:: js(code)
+.. role:: rst(code)
+.. role:: sep(strong)
+.. role:: typoscript(code)
+.. role:: ts(typoscript)
+   :class: typoscript
+.. role:: yaml(code)
+.. default-role:: code
+
+.. ---------
+.. highlight
+.. ---------
+.. Code blocks default to Python.
+.. highlight:: python
diff --git a/docs/source/how-to/how-to-how-to.rst b/docs/source/how-to/how-to-how-to.rst
@@ -0,0 +1,39 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: how-to-how-to ; Index
+
+
+.. _how-to-how-index:
+
+=============
+How-To How-To
+=============
+
+
+What
+----
+
+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?
+
+Why
+---
+
+Explanations aren't necessary when following a how-to guide. Adding descriptions is adding noise on the way to the goal.
+
+How
+---
+
+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.
+
+How-to guides don't need the repeatability of a tutorial, but they should be reliable.
+
+When
+----
+
+The goal of a how-to is to solve a problem or complete an unfamiliar task.
diff --git a/docs/source/how-to/index-how-to.rst b/docs/source/how-to/index-how-to.rst
@@ -0,0 +1,22 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: how-to ; Index
+
+
+.. _how-to-index:
+
+========
+How To's
+========
+
+|
+
+This index is a document framework placeholder for new How To's.
+
+|
+
+.. toctree::
+
+   :titlesonly:
+
+   how-to-how-to
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,51 +1,67 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: main ; Index
+
+
+.. _main-index:
+
 ====================================================
 Welcome to cookiecutter-py3-package's documentation!
 ====================================================
 
-Getting Started
----------------
+|
+
+See a list of the Original and new In Progress Documents below.
+
+|
 
 .. toctree::
-   :maxdepth: 2
+   :titlesonly:
+   :caption: Original Documentation:
 
    readme
    tutorial
+   prompts
    pypi_release_checklist
+   console_script_setup
+   troubleshooting
 
-Basics
-------
-
+|
+|
 .. toctree::
-   :maxdepth: 2
+   :titlesonly:
+   :caption: In Progress Documentation:
 
-   prompts
+   tutorials/index-tutorials
 
-Advanced Features
------------------
+|
+|
 
 .. toctree::
-   :maxdepth: 2
+   :titlesonly:
+   :caption: How-To's Placeholder:
+
+   how-to/index-how-to
 
-   console_script_setup
 
 
 Changelog
 ---------
 
 .. toctree::
    :maxdepth: 2
-   :caption: Contents:
 
    CHANGELOG-docs.md
 
 
+To Do List
+----------
 
+.. toctree::
+   :maxdepth: 2
+   :caption: ToDo:
 
-Todo List to improve cookiecutter-py3-package docs.
----------------------------------------------------
-
-.. todolist::
-
+   todo
 
 Indices and tables
 ==================

diff --git a/docs/source/prompts.rst b/docs/source/prompts.rst
@@ -1,7 +1,11 @@
+.. include:: /extras.rst.txt
+
 =======
 Prompts
 =======
 
+*Copyright 2015, Audrey Roy Greenfeld*
+
 When you create a package, you are prompted to enter these values.
 
 Templated Values

diff --git a/docs/source/pypi_release_checklist.rst b/docs/source/pypi_release_checklist.rst
@@ -2,6 +2,9 @@
 PyPI Release Checklist
 ======================
 
+*Copyright 2015, Audrey Roy Greenfeld*
+
+
 Before Your First Release
 -------------------------
 

diff --git a/docs/source/readme.rst b/docs/source/readme.rst
@@ -1,2 +1 @@
-
 .. include:: ../../README.rst
diff --git a/docs/source/todo.rst b/docs/source/todo.rst
@@ -0,0 +1,5 @@
+==================================================
+Todo List to improve cookiecutter-py3-package docs
+==================================================
+
+.. todolist::
diff --git a/docs/source/troubleshooting.rst b/docs/source/troubleshooting.rst
@@ -2,6 +2,8 @@
 Trouble Shooting
 ================
 
+*Copyright 2015, Audrey Roy Greenfeld*
+
 .. note:: Can you help improve this file? `Edit this file`_
           and submit a pull request with your improvements!
 

diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
@@ -2,6 +2,8 @@
 Tutorial
 ========
 
+*Copyright 2015, Audrey Roy Greenfeld*
+
 .. note:: Did you find any of these instructions confusing? `Edit this file`_
           and submit a pull request with your improvements!