feat(style):Create Intro to Diataxus #25

Create an introduction to Diataxus with brief explanations of the 4 document types.
Created a reST extra roles file, committed now because all reST files will need it.

WIP #25

docs/source/Diataxus/intro-diataxus.rst

@@ -0,0 +1,91 @@
+.. include:: /extras.rst.txt
+.. highlight:: rst
+.. index:: Diataxus; Introduction
+
+.. _intro-diataxus:
+
+=====================
+Diátaxis Introduction
+=====================
+
+
+
+Core values for using `Diátaxis  <https://diataxis.fr/>`__:
+
+*  A systematic framework for authoring technical documentation.
+
+*  Solves the challenge of structuring technical documentation.
+
+*  A systematic approach to understanding documentation users needs.
+
+The framework identifies four types of documentation:
+
+#. Tutorials:Learning Oriented
+#. How-to guides:Problem-Oriented
+#. Reference: Information Oriented
+#. Discussions: Understanding Oriented
+
+Each documentation type requires a different approach to its creation.
+
+Technical documentation should be structured explicitly around these four types and should keep them all separate and distinct from each other.
+
+.. figure:: /_static/img/diataxus-framework-1280x640.svg
+    :alt: Diataxus Framework
+    :align: center
+
+    Diataxus Framework
+
+
+Tutorials
+=========
+
+A tutorial helps a beginner achieve basic competence.  It needs to show that the learner can succeed by having them do something both meaningful and attainable.
+
+A tutorial is a lesson concerned with learning how rather than understanding why because it's practical, not theoretical.
+
+The work required to create and maintain tutorials is far more than is needed for the other types of documentation.
+
+For further interesting reading on this topic, see `Diátaxis Tutorials <https://diataxis.fr/tutorials/>`__
+
+
+How-to guides
+=============
+
+How-to guides are goal-oriented directions, much like a recipe. They take the reader through the steps required to solve a real-world problem.
+
+Examples could be calibrating a temperature sensor, using fixtures in pytest, and configuring a software package.
+
+Building a web application is not addressing a specific goal or problem. It's a vastly open-ended sphere of skill that is not a how-to.
+
+For further interesting reading on this topic, see `Diátaxis How-to <https://diataxis.fr/how-to-guides/>`__
+
+
+References
+==========
+
+References are technical descriptions of the machinery and how to operate it. References are information-oriented.
+
+References are like a map and should be to the point and wholly authoritative.
+
+References are consulted rather than read.
+
+Like a map tells you what you need to know about a region without going out and checking yourself,
+a reference serves the same purpose for the product and its internal machinery.
+
+For further interesting reading on this topic, see `Diátaxis References <https://diataxis.fr/reference/>`__
+
+
+Discussions
+===========
+
+Discussions clarify and illuminate a particular topic. Discussions are understanding-oriented.
+
+Discussions deepen and broaden the reader's understanding of a subject.
+
+Discussions aren't concerned with what the user might be doing, like tutorials and how-to guides.
+
+Discussions approach a topic from a higher perspective and from different angles that allow a more relaxed, more unrestrained way to consider something.
+
+Discussions join things together, and it makes sense to read while being away from the product itself.
+
+For further interesting reading on this topic, see `Diátaxis Explanation <https://diataxis.fr/explanation/>`__

docs/source/conf.py

@@ -10,9 +10,14 @@
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
-# import os
-# import sys
-# sys.path.insert(0, os.path.abspath('.'))
+import os
+import sys
+
+# This path didnt seem to work so commented out and added the one below.
+# Then changed it back again.  Its a mystery to me so left the optional fix just in case.
+# Found the fix here https://stackoverflow.com/questions/59903051/sphinxs-autodocs-automodule-having-apparently-no-effect
+sys.path.insert(0, os.path.abspath("."))
+# sys.path.insert(0, os.path.abspath(os.path.join("..", "..")))
 
 # -- Project information -----------------------------------------------------
 

docs/source/extras.rst.txt

@@ -0,0 +1,27 @@
+..  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