Welcome to Junction Box’s documentation!#

A place to document connections between technologies for our software development framework.

Document Framework#

This project is using the Diátaxis document framework.

The pages below are a summary of the original work created by Daniele Procida and links to the original work are included in the further reading section on each page.

Diátaxis Quickstart#

A summary of each document type and purpose.

1. Tutorial:#

Allow the learner to understand what goals they will achieve before they start.
A tutorial helps a beginner achieve basic competence.
Allow the user to learn by doing.
Get the learner productive and succeeding from the very start.

2. How-to:#

How-to guides are goal-oriented directions, much like a recipe.
The goal of a how-to is to solve a problem or complete an unfamiliar task.
Explanations aren’t necessary when following a how-to guide.
How-to guides should be flexible and adaptable to many use cases.

3. Reference:#

References are technical descriptions of the machinery and how to operate it.
A reference guides focus is the product and must describe it as succinctly as possible.
Users consult reference material, so it should not contain any ambiguity.

4. Discussions:#

Discussions clarify and illuminate a particular topic.
Discussions are understanding-oriented.
Discussions deepen and broaden the reader’s understanding of a subject.
Connections, even to things outside the immediate topic, can add clarity and context.

Diátaxis Introduction#

The Diátaxis Framework was developed by Daniele Procida.

Core values for using Diátaxis:

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.

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

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

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 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

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

Tutorials#

Summary#

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.

Dont be a teacher#

Allow the user to learn by doing; it’s how we know to walk and talk.

Give your learners things to do through which they can succeed and then begin to understand the subject.

As you lead the pupil through the steps of your tutorial, allow them to use the tools and perform the operations required to become familiar with the subject.

Build their knowledge up from the simplest tasks and ideas at the start to more complex ones as they progress.

Get Started#

Get the learner productive and succeeding from the very start.

Becoming an expert is not achievable here, and attempting this may lead our new contributors to self-doubt and drop out.

Please start at the very beginning: a user can pick up on the tutorial from new information, to them, begins.

If they need something and it’s not covered, the tutorial will seem incomplete to them, and you risk losing them.

It is ok if the tutorial would not be considered best practice by an experienced practitioner.

A beginners tutorial is a set of tasks that helps them set out safely on a journey of discovery, and it’s about the journey, not the destination.

It must work#

Ensure the beginner’s confidence by maintaining a friendly tone with consistent use of language.

The best way to maintain confidence is by providing a tutorial that works consistently.

Pinning all the requirements and using virtual environments can help in this endeavour for software development tutorials.

Documenting package requirements in the tutorial may be helpful for the long term maintenance of the tutorial, and preparing the beginner for further learning.

It’s challenging creating and maintaining a reliable tutorial experience.

Please aspire to create a reliable and interesting tutorial to guarantee your beginners success and enjoyment.

Instant Results#

Your learner is here to experience new and unfamiliar things.

Completing too many tasks before seeing a result from their actions may lead to a poor experience and retention rate.

Show the relationship between the cause and effect of each step very soon after, if possible.

Each step should be meaningful to the user.

Same Results#

The users of your tutorial will have different backgrounds and probably using various operating systems.

Repeatability and reliability can be challenging to achieve with these constraints.

Yet, your tutorial should work for all users, every time.

Testing your tutorials across the many possible environments ensures they will work as expected.

Concrete is your friend#

Tutorials should be composed of concrete steps, not abstract discussions.

Explicit is better than implicit regarding tutorial actions and outcomes.

Learning starts by meandering along concrete paths towards more general and abstract concepts.

After a beginner has walked many concrete paths, they are ready to see the patterns in them.

Expecting a learner to absorb abstract concepts in a beginner tutorial can be confusing and places an unnecessary burden on them.

Minimalism is the key#

Don’t provide explanations in the tutorial unless it is critical to the understanding of that step.

It’s enough to say - We are using HTTPS because it’s very secure. Discussion of HTTPS is essential in the proper learning phase but not in a tutorial.

When asking a user to do things without much explanation can appear problematic.

For the learner, it rarely is. The learner will focus on following directions and getting a result.

Cautious use of links to additional explanatory material may help.

Don’t interrupt the flow of a tutorial; adding links to a “Further Reading” section at the end of the tutorial keeps the clutter out.

Stay focussed#

Walking a concrete tutorial path may present exciting diversions along the way.

Remain focused on what’s required to reach the tutorial goals, and everything else can wait for another time.

Doing this keeps the tutorial more concise, saving you and the reader from the extra cognitive load.

How-to#

Summary#

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.

Tutorials -> How-to Guides#

How-to guides and Tutorials can easily overlap. However, How-to guides serve a different purpose to tutorials.

See the table below indicating the difference in the user’s needs as they move right along the learning path.

**Tutorials -> How-to Guides**#
Tutorials: for a Learner	How-to: for a User
May not know the right question.	Responsible for the right question.
Knowlege required is determined by the author.	Knowlege required is determined by the user.
Learner needs to be lead along the path.	User can choose their own path.
Learner aquires knowlege.	User applys knowlege.
Learner needs to be taught.	User needs to be shown.

Often How-to’s are better written than tutorials because they share the same focus as the developer.

The developer has moved past the learning stage, and a How-to is usually the focus of developers documentation.

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?

Following a recipe requires basic competence; a recipe is not a substitute for a cooking lesson.

Reading about the history of a recipe may be exciting, but it doesn’t help achieve the goal of the recipe.

The history of a recipe will provide the user with better value as they move right in the learning path towards the “discussion” phase.

Recipes follow a well-established format; similarly, How-to guides should also follow a format suitable for the technology.

For consistent formatting, The How-to guide could be in the form of a customisable template.

How-to write a How-to#

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.

Solving a Problem

The goal of a how-to is to solve a problem or complete an unfamiliar task.

Maintaining that focus throughout the how-to removes the mistake of bringing in “discussion” topics, which unnecessarily increase cognitive load.

No explanation needed

Explanations aren’t necessary when following a how-to guide. Adding descriptions is adding noise on the way to the goal.

Nice and flexible

How-to guides should be flexible and adaptable to many use cases, unlike a particular tutorial to a narrow topic.

Nothing unnecessary

Completeness is not a requirement of a how-to, whereas being practical and useable is.

How-to guides should start and end in a meaningful place and require the reader to apply it to their work.

What is in a name

Explicit is better than ambiguous when naming a how-to guide.

An explicit How-to name:

How to integrate application performance monitoring using XYZ.

It is clear what this how-to describes.

An ambiguous How-to name:

Integrating application performance monitoring.

Perhaps this document is about the question of deciding whether you should Integrate application performance or not, or something entirely different.

A terrible How-to name:

Application performance monitoring.

This name is very general and does not suggest a how-to guide. Perhaps it’s a book title.

Note

Search engines make use of good document names.

Reference#

Summary#

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 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.

About#

A reference guides focus is the product and must describe it as succinctly as possible.

Reference guides differ from tutorials and how-to’s, where the user needs are the focus.

Software reference guides describe how to use the APIs, classes, functions and so on.

Users see reference material as the source of truth.

An excellent technical reference provides users with confidence to perform their work when using that product.

Description#

Users consult reference material, so it should not contain any ambiguity.

Reference material is akin to a map and shares the same purpose as a map for the product it references.

Reference material should not show how to perform tasks but should describe how something works or the correct way to use it.

Tools exist, such as Sphinx, that can auto document software API’s using docstrings. Sphinx is a convenient way to keep API documentation relevant.

Its not a recipe#

Reference guides, like an encyclopedia, will be consulted for information on the given topic.

For example, if you consider a recipe, there is a list of ingredients but no explanation of what that ingredient is.

An encyclopedia shines here, providing up to date concise information about the ingredient.

The focus of information delivery for a reference guide is much the same as an encyclopedia.

How-to write a Reference#

Mirror Structure

A map conveys the structure of the area it maps. Likewise, a reference guide should represent the structure of the product it references.

For example, a software reference guide should follow the software’s architecture.

What we mean by following the software architecture is that the conceptual and logical arrangement of the reference guides parts should mirror that of the software where possible.

Consistency

Write consistency into references from six essential areas:

Concise factual information.
Consistent logo or branding placement.
Consistent colours.
Consistent tone in writing.
Consistent imagery.
Consistent Typography, layout and formatting.

Writing tone is possibly the most important, with intelligent use of language that is purposeful and doesn’t use uncommon or obscure words where possible.

Just Describe

A reference is a concise, factual document, so there is no room for speculation, opinions, or discussion.

Reference guides may sometimes seem bare; however, providing links to tutorials and how-to’s where appropriate is better than confusing the focus of the reference.

Examples

Good examples can help the reader connect ideas, concepts and how the machinery interacts with each other, especially if they involve levels of abstraction.

Discussions#

Summary#

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.

About#

Discussion clarifies a particular topic. Discussions are understanding-oriented which broadens the reader’s understanding of the subject.

Discussion documentation provides a more relaxed way to consider a subject and joins things together. Often it makes sense to read while away from the product in a more comfortable environment.

Description#

Discussion documentation doesn’t have a natural part in the user’s practice or work, which can appear to reduce its importance.

Discussion documentation may be less urgent than tutorials, how-tos and reference documentation, but it is no less critical.

Discussion documentation is explanatory information that weaves it all together. Without discussion documentation, the users grasping and holding onto the subject concepts can be diminished.

Boundaries#

Writing good discussion documentation is difficult due to the open-ended nature of its scope.

Rarely is specific discussion documentation written; it is more likely to be scattered in small sections throughout tutorials, how-tos and references.

One place to start writing good discussion documentation is with a question, Why? From here, it is possible to set some rough scope boundaries to get started.

FAQ can provide a subject to get started; here are real-world reasons to write a discussion document.

How-to write Discussions#

Connections

Discussions help spin the web of understanding for your readers. Connections, even to things outside the immediate topic, can add clarity and context.

Context

Tell a story—the background and why things have progressed to this point, historical reasons, design decisions, statutory obligations, and technical constraints may all be part of the story.

If a good example can be shared, that provides additional context, then consider including that.

Whats in a name

Naming your discussion can be either explicit or implicit. The discussion document is a high-level view of the subject; therefore, being precise is not required.

Just an opinion

Consider alternatives and other options in your discussion. Discussing pro’s and cons opens up the topic to be more informative and perhaps guide the reader onto other material in their quest for knowledge.

Discussions may sometimes seem bare; however, providing links to tutorials, how-to’s and reference material where appropriate is better than confusing the the focus of the discussion.

Document Templates#

See a list of the Document Templates we have completed below.

Index Template#

Use the copy button and paste the template into your new index.

Note

Change the highlighted line numbers 3, 6 and 8 to suit you use case.

Tip

Remove the optional highlighted toctree options that aren’t required.

See Sphinx toctree for more information about toctree options.

Index Page Template#

.. include:: /extras.rst.txt
.. highlight:: rst
.. index:: template-index ; Index


.. _template-index:
================
Index Title Here
================

An optional brief description describes the index.


.. toctree::
   :titlesonly:
   :maxdepth: int
   :hidden:
   :caption:
   :includehidden:
   :reversed:
   :numbered:
   :glob:

Format to include pages in the TOC#

    to include .rst files in the TOC

    /path-to-first-page
    /path-to-second-page

    to include markdown files in the TOC use the full name with file extension

    /path/to/markdown-file.md

reST Documentation#

What is it: One or two lines description

Why does it exist: One or two lines description

How-to#

How-to: Write one or two lines describing the in-depth explanation that follows.

Use admonitions, inline-tabs and other reST tools to get a concise message across.

How it Looks

Demonstrate what the reST code will look like here.

reST syntax

1Add reST here

Reference#

Many other examples follow below, in the How it Looks and reST syntax tabs.

First Example#

How it Looks

Have reST syntax to render how an example looks here.

reST syntax

1Have the reST syntax here; this should mirror the How it Looks tab.

Discussion#

Tutorial Template#

Two Tutorial Template copy options are available:

Copy a tutorial template with some examples and hints in each section to help you get started.
Copy an empty tutorial template framework.

Use the copy button and paste the tutorial template into your new tutorial.

See the rst code in Template with Examples rendered here.

Important

The highlighted items are the template parts to modify for your use case.

Examples provided in the Tutorial body are for demonstration purposes.

Delete any examples that you wish to.

Template with Examples

Highlighted lines require author input.#

.. include:: /extras.rst.txt
.. highlight:: rst
.. index:: template-tutorial ; Index


.. _template-tutorial:
================
Name of Tutorial
================

|

A brief description about the tutorials aims.

.. admonition:: Example - Using Admonitions

    Use notes to bring something to the user's attention where it improves
    user experience.

    See `Write a tutorial using Diataxis <https://junction-box.readthedocs.io/en/
    latest/Document-Framework/diataxis-tutorials.html>`_
    for assistance on how to write a well-structured tutorial.

|

Pre-requisites
==============

Examples of pre-requisites

`Python 3.6 <https://www.python.org/downloads/>`_ or greater installed on
your computer.

:ref:`Create an index page.<template-index>`


.. _the-name-tutorial:
Tutorial
========



.. _first-step-title:
First Step Title
----------------

Select the tab for your preferred Operating System.

.. admonition:: Example - Using Admonitions

    You can use numbered step headings; however, well-described titles appear
    to flow in the TOC.

    Using Tabs can condense the page and group logical items together,
    for example, different Operating Systems have various commands
    to achieve the same outcome.

    See this example below.

.. tab:: Linux

    Do some linux command.

.. tab:: macOS

    Do some macOS command.

.. tab:: Windows

    Do some Windows command.

Whats next?
-----------

.. hint::

    Here you can guide the user to expand their knowlege with relevant
    information.

    For example:

    See `Diataxis Introduction <https://junction-box.readthedocs.io/en/latest/Document-Framework/diataxis-intro.html>`_
    for more information about writing documentation.

Template Framework Only

Highlighted lines require author input.#

.. include:: /extras.rst.txt
.. highlight:: rst
.. index:: template-tutorial ; Index


.. _template-tutorial:
================
Name of Tutorial
================

|

A brief description about the tutorials aims.

|

Pre-requisites
==============

|

.. _the-name-tutorial:
Tutorial
========

|

.. _first-step-title:
First Step Title
----------------

|

Whats next?
-----------

An index for design ideas chosen or considered for our project.

Design Principles#

Design UX Introduction#

Summary#

User experience aims to provide positive experiences for the user. Some benefits are:

Reduce cognitive load on the user to complete a task.
Help improve user productivity.
Improve customer loyalty.
Help improve the customers’ journey to ensure business success.

UX design process summary#

Clever user experience design starts by following a simple process of

Identifying the users’ problem.
Listening and steering ideas to the solution.

Using Who, What, Why, How and When logic, we can build a simple design framework to get started. Some ideas are listed below.

Who has the problem?
1. end-users,
2. a business group or
3. others.
What is the problem?
1. Can the problem be solved with a UX design solution?
2. What features will solve the problem?
Why do users need this solution?
1. Has the need been well defined?
2. Has the benefit been well defined?
How will the solution be implemented?
When will the solution be required?
1. This stage is for budget and resource estimates.

UX Design process detail#

Who#

Getting to know the users allows you to understand their needs and gives them a voice in the solution.
Create a user persona representing a particular user of the product or service you are designing.

What#

The design process may combine some or all of these suggestions.

Conduct business representative interviews to understand the business needs. are under consideration?
Conduct user interviews and, where possible, spend time with them interacting with their existing system.
Write short descriptions of the features the user would like and the problems it will solve.

Why#

Clearly define each “problem” and each “benefit” in a report from information gathered in the “What” step.

How#

Some things to help complete this step are:

Functionality mapping: This is a hierarchy of pages and subpages. Functionality maps can help accurately map user workflows.
Wireframes: Visual guides to how the solution looks and feels. Users can use wireframes to provide input to remove useability issues before the development process begins.
Prototype: A mockup of the final product.
User testing: Users have the prototype to test and resolve issues before going to development.

When#

Often this is the first thing you need to understand; it can drive all the other steps timeframes, resource allocation and so on.

UX Design Tips#

Here are eight tips to help improve the UX design process:

Rely on a design system, for example, Figma.
Create a natural flow through the User Interface.
1. Starting left and moving right is one natural flow style; there may be others more valuable. What’s important is to follow the natural flow identified.
2. Following a left to right workflow, to go back, the user sees this as moving left, so the “back” button should be on the left side of the screen, not the right.
3. Following a left to right workflow, the “previous” button is on the left, and the “next” button is on the right.
Colours have meaning.
1. A simple system is
  1. Errors are red.
  2. Warnings are orange.
  3. Ok is green.
2. Use one colour for clickable components and other colours for accents.
  1. Using opacity can assist with the appearance of flows by reducing the visual impact and alerting the user.
  2. Icons can provide additional information to the user if coloured and positioned appropriately.
Have a single primary clickable action per screen.
1. Decide what the primary purpose of the screen is.
2. Make any clickable actions on the screen less prominent, for example, changing them to outline instead of solid colour.
Separate navigation from actions.
1. Be obvious between the navigation and action settings within navigation bars, e.g. use buttons to distinguish the differences.
Make your user interface predictable.
1. Be careful adding and removing dynamic elements from the interface.
2. Good example
  1. Disable <send email> action button while no user selected
  2. Enable <send email> action button when a user is selected.
3. Bad example
  1. Hide <send email> action button while no user selected
  2. Show <send email> action button when a user is selected.
Use space to separate things.
1. Use spacing to define grouped items.
2. Use spacing to define different user interface sections.
Build an intuitive interface for the user.
1. The user interface should make the users’ experience as easy as possible.
2. Don’t design the user interface around how the system works.
  1. When user input is required for an action to occur, e.g. selecting a check box, action buttons for that action should be disabled until user input is received.
  2. When valid user input is required for an action to occur, e.g. an email address, action buttons should be disabled until validated user input is received.

These eight steps have been summarised from this fantastic tutorial about UX Design by ArjanCodes.

Design with Tailwind css and Figma#

Tailwindcss, a utility first CSS framework with classes that can be composed to build any website design directly in your markup.

Figma, a free UX design tool, allows the entire team to interact with the latest web design by accessing a single, live URL.

Figma helps teams create, test, and ship better website designs from start to finish.

Figma Tutorial#

Figma 101 by CharliMarieTV

Tailwind Tutorials#

Tailwind Labs Youtube channel

Tailwind from zero to hero series

Figma & Tailwind - Build Sign-in and Registration forms with Auto Layout and grids

Generally we follow PEP 8 in our Python code.

Style Guides#

Style Guide#

What#

Style guides provide guidelines for presenting your Brand from a visual and written perspective.

How#

Provide well-written style guides developed from six essential areas:

Your story.
Your logo.
Your colours.
Your voice.
Your imagery.
and Typography.

Why#

Style guides establish consistent usage of language and layout across several different contributors.

Well structured and written style guides, including layouts for the four pillars of Diátaxis content framework, reduce the load on technical and content creators.

When#

Right now is an excellent time to start.

See our list of style guides below.

Tip

Style guides are under construction… More to come : )

Developer Styles#

Git#

Commit Message#

The git commit message follows the Conventional Commits style.

# tag(subject):<Description>  #nn being the issue number if it exists
# (subject): CHANGELOG update groups items with the same subject.
# |<----   Preferably using up to 50 chars   --->|<--Max of 72 chars-->|
# Example: docs(style):Added a new reST style guide #42


# (Optional) Explain why this change is being made
# |<----   Try To Limit Each Line to a Maximum Of 72 Characters   ---->|
# Example: There wasnt a reST style guide.


# (Optional) Provide links or keys to any relevant tickets, articles or other resources
# Example: closes #42


# --- COMMIT END ---
# Tags with ** will be included in the CHANGELOG
# **   chore    (a chore that needs to be done)
#      dbg      (changes in debugging code/frameworks; no production code change)
#      defaults (changes default options)
# **   docs      (changes to documentation)
# **   feat     (new feature)
# **   fix      (bug fix)
#      hack     (temporary fix to make things move forward; please avoid it)
#      license  (edits regarding licensing; no production code change)
# **   perf     (performance improvement)
# **   refactor (refactoring code)
# **   style    (formatting, missing semi colons, etc; no code change)
# **   test     (adding or refactoring tests; no production code change)
#      version  (version bump/new release; no production code change)
#      WIP      (Work In Progress; for intermediate commits to keep patches reasonably sized)
#      jsrXXX   (patches related to the implementation of jsrXXX, where XXX the JSR number)
#      jdkX     (patches related to supporting jdkX as the host VM, where X the JDK version)
#
# --------------------
# Remember to:
#   * Capitalize the subject line start
#   * Use the imperative mood in the subject line
#   * Do not end the subject line with a period
#   * Separate subject from body with a blank line
#   * Use the body to explain what and why vs. how
#   * Can use multiple lines with "-" or "*" for bullet points in body
# --------------------

Important

For Auto-generate CHANGELOG Github Action to pick up the changes, the heading must be in the following format.

tag(subject):<Description> #nn being the issue number if it exists

Example: docs(style):Added a new reST style guide #42

(subject): The CHANGELOG’s update groups items with the same subject.

CHANGELOG#

Two Auto-generate CHANGELOG yaml files use BobAnkh/auto-generate-changelog.

The first, below, updates the CHANGELOG for the repo and includes additional tags to assist the developers, particularly with WIP.

Important

Don’t forget to change line 21 REPO_NAME if you are using this for your Github repo.

Important

Don’t forget to change line 22 REPO_NAME if you are using this for your Github repo.

More to come:

reStructured Text Style#

There may be a need to modify one of the pre-existing templates or create a new one to improve how the author can convey their message.

For those occasions, here is Junction Box’s reST styling guide.

Text Emphasis#

Bold and Italic#

Sphinx can render text as either bold or italic but not both.

1Normal text, **bold text** and *italic text*.

See the styling above rendered by Sphinx below.

Normal text, bold text and italic text.

Line Spaces#

Line spaces can help emphasise text in some cases.

Text not separated by a blank line will join.

Blank lines in reST don’t render as blank lines in the document.

Line spaces will render when using the | symbol.

   Text on line 1
   Text on line 2

   Text on line 4

   |

   Text on line 6

See the styling above rendered by Sphinx below.

Text on line 1 Text on line 2

Text on line 4

Text on line 6

Important

See the effect of no line separation between Text on line 1 and Text on Line 2.

| symbol is not rendered but provides a clean line space.

Document Headings#

In reST, you can use different underlining styles in any order.

For reST (.rst) Title and Heading styles, see below.

   ========
   DocTitle
   ========

   Heading 1
   =========

   Heading 1.1
   -----------

   Heading 1.1.1
   ~~~~~~~~~~~~~

   Heading 1.1.1.1
   """""""""""""""

See the styling above rendered by Sphinx below.

DocTitle#

Heading 1#

Heading 1.1#

Heading 1.1.1#

Heading 1.1.1.1#

Links#

Link to a Heading#

Sphinx provides the ability to link to internal document references.

.. _random-heading:

Random Heading
==============

Some random text to help with some unexpected challenges.

See here :ref:`random-heading` for information to help with your unexpected challenge.

Important

Sphinx is sensitive to line spaces in this scenario.

If your link doesn’t appear, check for an empty line between the internal link reference and the heading declaration.

See the styling above rendered by Sphinx below.

Random Heading#

Some random text to help some unexpected challenge.

Scroll down so “Random Heading” is off the screen, and click the hyperlink to see the internal linking in action.

See here Random Heading for information to help with your unexpected challenge.

Important

The :ref:`random heading-link` text is surrounded by backticks, not single apostrophe’s!

API Summary Index#

This page displays how autosummary displays the API summary.

Click one of the options below to see autoclasstoc grouping.

Sphinx Examples#

`environment.BuildEnvironment`(app)	The environment in which the ReST files are translated.
`util.relative_uri`(to)	Return a relative URL from `base` to `to`.

Local Examples#

`reST_docstrings_example.MainClass1`()	This class docstring shows how to use sphinx and rst syntax
`simple_calculators_example`	A very very simple set of calculators

Indices and tables#

About#

JUNCTION BOX#

What’s in a name?#

The process of writing software is very similar to the electrical trade in the sense that things are wired up or connected.

Hence the name Junction Box, a place where things are connected.

Overview#

This project is about documenting how we use several technologies that meet the needs of our software development initiatives.

What#

To kick-off, we will be exploring and documenting these technologies:

Diátaxis: A documentation content organisation framework.
Sphinx: A document building tool.

When how we use the first two items has been documented, other technologies on our list include:

Continuous Delivery: Dave Farley Style.
Django: A python web framework.
Pytest: A software testing tool.
Hypothesis: A software testing tool.
Playwright: End-to-end testing for modern web apps.

How#

Create and follow a style guide.
Create standard layouts for content.
Follow the Diátaxis document content framework.
Only record what we have used and tested.

Why#

You want people to use your project.
If you have good documentation, people are more likely to use your project.
If people are more likely to use your project, you will have more contributors.
If people have trouble installing your project with poor documentation, they are more likely to opt out.

Continuous documentation is a critical task often overlooked or poorly executed.

Over time as memories fade, the need for good quality documentation becomes evident.

Things that make sense now often don’t make sense later.

When it is needed, good documentation can ease the load of remembering.

This may help some one else!

When#

Following Continuous Delivery Principles, this is a living document.

The Author#

Mark Sevelj has an electrical trade background.

Roles where often technical and using Python and pandas for data analysis was a lot faster than excel.

A need to formalise and document these scripts and workflows is the purpose of this project.

CHANGELOG#

v0.7.1 (2021-11-01)#

Fix#

how-to: Main index link updated to new location #215 (aa76a29)

v0.7.0 (2021-11-01)#

Feature#

how-to: Reorganise structure, add CLI cheatsheet #213 (cac844a)

v0.6.0 (2021-11-01)#

Feature#

docs: Add Diataxis quickstart document #209 (064fa1b)

Fix#

pyup: Exclude autoclasstoc from checks #210 (a1e68f0)

v0.5.1 (2021-10-31)#

Fix#

docs: Move changelog to docs folder #202 (0a3f093)

v0.5.0 (2021-10-31)#

Feature#

docs: Add additional Tutorial Template #199 (629e1f0)

v0.4.1 (2021-10-31)#

Fix#

docs: Fix version source in conf.py #194 (a862ebd)

v0.4.0 (2021-10-31)#

Feature#

docs: Add sem-ver changelog to docs #190 (811b056)

v0.3.1 (2021-10-31)#

Fix#

deps: Tidy up requirements.txt unused deps #188 (5bd1772)

v0.3.0 (2021-10-30)#

Feature#

pyup: Add pyup dependency checks and badge #186 (4721097)

v0.2.1 (2021-10-30)#

Fix#

docs: Update autoclasstoc version #177 (d0267cc)

v0.2.0 (2021-10-30)#

Feature#

sem-ver: Add semantic versioning and changelog #179 (f5e57bc)
sphinx: Add support for markdown #49 (ab2b705)
sphinx: Theme is now t3SphinxThemeRtd #12 (86f3afb)
sphinx: Added custom theme furo #12 (e3f351b)
sphinx: Update requirements.txt (7403cd7)
sphinx: Install with base config (75a8fb5)
pre-commit: Add tox.ini (6db58b0)
pre-commit: Add pyproject.toml file (cce2a1c)
pre-commit: Add yaml config file (8cc0799)
#6: Add chore to CHANGELOG choices (4ae4a80)
#6: Delete CHANGELOG template (35f489c)
#6: Update CHANGELOG yaml (b9920f1)

Fix#

Requirements.txt to reduce vulnerabilities (274d64f)
sphinx: Spinx-inline-tabs broken (36d9242)
sphinx: Readthedocs build failed (pkg-resources==0.0.0) #18 (581a99d)

Documentation#

CHANGELOG: Update release notes:docs (f0813f1)
CHANGELOG: Update release notes:docs (c152c4b)
CHANGELOG: Update release notes:repo (1411cb9)
CHANGELOG: Update release notes:docs (563546a)
CHANGELOG: Update release notes:repo (5502a5a)
CHANGELOG: Update release notes:docs (aa674e1)
CHANGELOG: Update release notes:docs (e1957f9)
CHANGELOG: Update release notes:repo (b9e876e)
CHANGELOG: Update release notes:docs (9d18e64)
CHANGELOG: Update release notes:docs (d2175e5)
CHANGELOG: Update release notes:repo (5c6c34b)
CHANGELOG: Update release notes:docs (ce0c91e)
CHANGELOG: Update release notes:docs (1193d92)
CHANGELOG: Update release notes:docs (76b8520)
CHANGELOG: Update release notes:docs (64bc9ec)
CHANGELOG: Update release notes:repo (f0e33b1)
CHANGELOG: Update release notes:docs (936a719)
CHANGELOG: Update release notes:docs (e54add2)
CHANGELOG: Update release notes:docs (9b70bb0)
CHANGELOG: Update release notes:docs (cc9edc0)
CHANGELOG: Update release notes:docs (3508096)
CHANGELOG: Update release notes:docs (96f9e90)
CHANGELOG: Update release notes:repo (c1565b9)
CHANGELOG: Update release notes:docs (87a4663)
CHANGELOG: Update release notes:repo (3dbf7ee)
CHANGELOG: Update release notes:docs (341aaab)
CHANGELOG: Update release notes:repo (a2f8197)
CHANGELOG: Update release notes:repo (166335b)
images: Add .png and .svg diataxus #25 (a360ff5)
CHANGELOG: Update release notes:repo (c3d14c8)
style: Created how-to-diataxus.rst #25 (0aa9d46)
CHANGELOG: Update release notes:repo (f110fcb)
CHANGELOG: Update release notes:docs (0e69c24)
CHANGELOG: Update release notes:repo (b5fd747)
CHANGELOG: Update release notes:docs (8c80c10)
CHANGELOG: Update release notes:repo (d413a53)
CHANGELOG: Update release notes:docs (4d5bf27)
CHANGELOG: Update release notes:repo (db05b56)
CHANGELOG: Update release notes:docs (71f7584)
CHANGELOG: Update release notes:repo (34528f1)
CHANGELOG: Update release notes:docs (cd863a7)
CHANGELOG: Update release notes:repo (0ee2349)
CHANGELOG: Update release notes (4d107f5)
CHANGELOG: Update release notes (3e099b4)
CHANGELOG: Update release notes (598084d)
CHANGELOG: Update release notes (d775868)
CHANGELOG: Update release notes (ce23157)
CHANGELOG: Update release notes (d492b4d)
images: Add .png and .svg logo’s #37 (1c7abc3)
CHANGELOG: Update release notes (c824da2)
style: Add Development Pipeline style #35 (c9847bb)
CHANGELOG: Update release notes (acb6de2)
CHANGELOG: Update release notes (5451668)
CHANGELOG: Update release notes (8ca36f8)
CHANGELOG: Update release notes (952f6ef)
Style: Add intro Style Guide, Update Index (2df9ad0)
CHANGELOG: Update release notes (063c3e5)
about: Improve wording in the Why section (ec5c76e)
CHANGELOG: Update release notes (6b2eb6f)
CHANGELOG: Update release notes (6a88c33)
README: Add a link to the readthedocs docs (2f4159d)
CHANGELOG: Update release notes (6d4aeee)
about: Add an about page, update index (09c9cc1)
CHANGELOG: Update release notes (312f31c)
CHANGELOG: Update release notes (e95580b)
CHANGELOG: Update release notes (37306fa)
CHANGELOG: Update release notes (71ad5b6)
CHANGELOG: Update release notes (645662f)
CHANGELOG: Update release notes (c12a15f)
CHANGELOG: Update release notes (8478039)
CHANGELOG: Update release notes (83a0228)
CHANGELOG: Update release notes (e529d8c)

Chore#

docs:
- Fixed transition titleblock #149 (7b82d92) (#150)
- Fixed damaged link #149 (d7b7d00) (#150)
- Fixed linking errors #149 (8e6ce6f) (#150)
- Remove ref to deleted doc #149 (80487f1) (#150)
- Delete unused file #149 (83e2e53) (#150)
- Deleted ununsed document #149 (c614b7b) (#150)
- Fix lineblock error #149 (f2f1709) (#150)
- Remove transistion error #149 (fa3e293) (#150)
- fix Title underline too short #149 (b804684) (#150)
- Fix incorrect use of directive #149 (6c1cd48) (#150)
- Fix 2 rows of ` errors #149 (4af88eb) (#150)
pre-commit:
- Remove `` check (dc8e9fd) (#150)
reST:
- Added example files for docs #139 (f12c7fa) (#140)
files:
- readthedocs.yaml tweak (0e72fa3) (#131)
- readthedocs.yaml tweak (75bcc96) (#130)
- Pinned sphinx-inline-tabs==2021.4.11b9 (61b4163) (#129)
- Pinned sphinx-inline-==2021.4.11b9 (aa23f81) (#128)
file:
- Fix python version for readthedocs (1687e1f) (#127)
- Rename .readthedocs.yml (099522f) (#126)
readthedocs:
- Added yaml config file (33fb345) (#126)
conf:
- Update to latest release (4cb3576) (#106)

Feature#

sphinx:
- Added autodoc extension #144 (00559c6) (#147)
- Add inline text support #121 (1464634) (#123)
- Add copy-button to code-blocks #110 (b2cfcee) (#111)
discussion:
- Links to discussion board #118 (345e441) (#119)

Bug Fixes#

sphinx:
- Regex for copy button improved #136 (74d122d) (#137)
- spinx-inline-tabs broken (36d9242) (#125)
- sphinx-inline-tabs==2021.4.11b9 missing (36d994f) (#124)
- New regex for copy-button #112 (094e00c) (#120)
git:
- Fix typo in .git-commit-template.txt (504d6aa) (#116)

Documentation#

sphinx:
- Add files for autodoc #145 (f4caa81) (#157)
template:
- Updated reST template #148 (9b59b34) (#156)
- Added reST #148 (fb03281) (#150)
reST:
- Added diff to literalinclude options (0870244) (#156)
- Add a reST documentation template #142 (1e9e566) (#143)
- Added literalinclude document #135 (cb6db79) (#141)
- Updated index and renamed file (823150e) (#138)
- Added Titles and Headings #66 (de90bcf) (#138)
- Added reST-admonitions #64 (43b4baf) (#133)
- Added introduction and update index #65 (dac78e9) (#132)
- Added inline-tabs.rst #122 (fd8e8c7) (#123)
Autodoc:
- Added config and docs to test #145 (bc997fa) (#153)
style:
- Added pep 8 reference to styling index (98fb6de) (#153)
- Updated .git-commit-template.txt (3f32fae) (#117)
- Fix typo style-developers.rst (14ccb60) (#105)
index:
- Multiple file rename index fixes #146 (11c0f96) (#152)
- Multiple file index fixes #146 (328319d) (#151)
- Added index template #146 (5677a65) (#151)

Styling#

reST:
- Change code-block->literalinclude #154 (67e6d87) (#156)
- Change code-block->literalinclude #154 (7b0b09f) (#156)
- Admonitions fixed some typos #64 (b73c740) (#138)
- Admonitions layout tweaks #64 (6532329) (#134)

Tests#

sphinx:
- Testing autoclasstoc feature #145 (4b7df48) (#163)
- Testing autoclasstoc feature #145 (1a433e6) (#162)
- Testing autoclasstoc feature #145 (81b95bd) (#161)
- Testing autoclasstoc feature #145 (82141cc) (#160)
- Testing autoclasstoc feature #145 (f2be741) (#159)
- Testing autoclasstoc feature #145 (6048a3a) (#159)
- Testing autoclasstoc feature #145 (e7a9d88) (#158)

v0.0.1-alpha-2 - 2021-07-19 03:32:22#

Completed some Style guides and Diátaxis documentation. A reasonable body of work to release and clean up the In Progress list.

Chore#

files:
- Added folder, rename files for TOC #62 (130809b) (#104)
- Rename folder and file for TOC #62 (ba723a5) (#104)
- Fix more common misspelling of diataxis (11f3014) (#103)
- Fix common mispelling of diataxis (6827ec3) (#102)
- Housekeeping adding img/diataxus files (cb5bb26) (#78)
- Files deleted housekeeping img/ (afd496e) (#77)
- Housekeeping deleted files (9163f96) (#76)
- Added a img/diataxus folder (a781529) (#75)
- Rename and fix links to the logo images (274d296) (#72)
- Rename and fix links to the file (6a689b6) (#68)
file:
- Renamed tutorials-diataxus #25 (fa78293) (#91)
- Delete intro-diataxus #25 (ca58e80) (#90)
- Diataxus/how-to-diataxus.rst #25 (e6fa853) (#89)
- Files renamed to be deleted #25 (57bb30c) (#87)
- Rename 2 diataxus files for style #25 (3901969) (#86)
log:
- update-changelog.yaml on push removed (f5ce7fe) (#71)
- update-changelog.yaml Types tweaked (a2fc239) (#70)

Feature#

sphinx:
- Theme is now Furo (eb4b170) (#104)
- Add support for markdown #49 (ab2b705) (#51)
- Theme is now sphinx_rtd_theme (97174c7) (#29)
- Theme is now t3SphinxThemeRtd #12 (86f3afb) (#27)
docs:
- Add content developers style guide #35 (76dbe8e) (#98)
- Created diataxus-discussion doc #25 (2b03d6c) (#96)
style:
- Add logo images #25 (11e02d0) (#80)
- Created diataxis tute and intro #25 (d030edf) (#74)
- Create Intro to Diataxus #25 (d5c6a19) (#73)

Bug Fixes#

log:
- Corrected time in cron to 1400 #100 (9810148) (#101)
- fix(log)Split changelog update now 2 files #93 (12ea44e) (#97)
- CHANGELOG now updates on push #60 (eea8e08) (#61)
- Added CHANGELOG.md to /docs/source #58 (9269a54) (#59)
- Changed yaml /source/CHANGELOG #58 (e6d3c8f) (#59)
yaml:
- Cron job not formatted correctly (a64530e) (#34)

Documentation#

images:
- Add .png and .svg diataxus #25 (a360ff5) (#94)
- Add .png and .svg logo’s #37 (1c7abc3) (#38)
style:
- Created how-to-diataxus.rst #25 (0aa9d46) (#85)
- Added content style-rst.rst #23 (7bb4d14) (#82)
- Updated index.rst with extras.rst.txt (63e844e) (#81)
- Update Development Pipeline style #35 (2b37173) (#47)
- Update Commit Message template #41 (b0c05bb) (#46)
- Update Development Pipeline style #35 (608574f) (#46)
- Add Development Pipeline style #35 (c9847bb) (#36)
- Added reST style guide. TOC update #23 (78aad68) (#32)
README:
- Added a link to youtube Diátaxis (97dda99) (#67)
- Added readthedocs status badge #52 (de9786b) (#53)
- Added logo to the git README #37 (7be1e99) (#39)
log:
- Add CHANGELOG to the docs #56 (c27e973) (#57)
- update-changelog.yaml cron now UTC2300 #54 (0d6c20c) (#55)
- Add additional tags to update-changelog.yaml# (dce6027) (#45)
about:
- Added content to the WHY section. (8446c68) (#50)
- Change to match reST style guide. (230dd44) (#31)
- Improve wording in the Why section (ec5c76e) (#26)
Style:
- Add intro Style Guide, Update Index (2df9ad0) (#30)

In Progress#

style:
- Tweaked 2 diataxus file content #25 (473eace) (#96)
- Added content diataxus-reference.rst #25 (ebb761a) (#92)
- Update content diataxus-intro.rst #25 (ea996f4) (#92)
- Fix asccidental deletion of how-to #25 (cffef71)
- Fixed accidental deletion of how-to #25 (99ca891)
- Added diataxus-reference images #25 (ba4aa64) (#86)
- Added content to tutorial-diataxus #25 (95e1910) (#84)
- Added content to intro-diataxus #25 (3f3f328) (#83)
- Diataxus style tutorial update index #25 (afcded3) (#79)
- Diataxus style intro update index #25 (98a7e6b) (#79)
log:
- Comment out second BobAnkh job to test #93 (7f44350) (#95)
DOCS:
- Add Diataxus framework images, png, svg #25 (a4088c1) (#69)
images:
- Updated the .png and .svg logos #37 (28e97fa) (#40)

v0.0.1-alpha-1 - 2021-07-08 07:35:04#

Sphinx and the Furo theme have been installed with basic configurations. A basic about page was written and deployed to readthedocs. Snyk was deployed to monitor this project.

Feature#

sphinx:
- Added custom theme furo #12 (e3f351b) (#20)
- Update requirements.txt (7403cd7) (#16)
- Install with base config (75a8fb5) (#15)

Bug Fixes#

sphinx:
- readthedocs build failed (pkg-resources==0.0.0) #18 (581a99d) (#19)

Documentation#

README:
- Add a link to the readthedocs docs (2f4159d) (#22)
about:
- Add an about page, update index (09c9cc1) (#21)

v0.0.1-alpha - 2021-07-07 08:23:31#

Basic git workflow setup.

Chore#

venv:
- Added requirements.txt (4eef7b4) (#9)

Feature#

pre-commit:
- Add tox.ini (6db58b0) (#10)
- Add pyproject.toml file (cce2a1c) (#10)
- Add yaml config file (8cc0799) (#10)
#6:
- Add chore to CHANGELOG choices https://www.conventionalcommits.org/en/v1.0.0/ allows other choices for commit. Chore was added because it was missing in our choices. This change adds additional flexibility for categorizing commit messages. issue (#6) (4ae4a80) (#9)
- Delete CHANGELOG template The template is no longer required for this feature upgrade. issue #6 (35f489c) (#7)
- Update CHANGELOG yaml Rewrite update-changelog.yaml and point it to https://github.com/BobAnkh/auto-generate-changelog issue #6 (b9920f1) (#7)

* This CHANGELOG was automatically generated by auto-generate-changelog

Would you mind providing feedback or creating a discussion on our GitHub discussion board?

Welcome to Junction Box’s documentation!#

Document Framework#

Diátaxis Quickstart#

1. Tutorial:#

2. How-to:#

3. Reference:#

4. Discussions:#

Further Reading#

Diátaxis Introduction#

Tutorials#

How-to guides#

References#

Discussions#

Tutorials#

Summary#

Dont be a teacher#

Get Started#

Share the full view#

It must work#

Instant Results#

Same Results#

Concrete is your friend#

Minimalism is the key#

Stay focussed#

Further Reading#

How-to#

Summary#

Tutorials -> How-to Guides#

Its a Recipe#

How-to write a How-to#

Further Reading#

Reference#

Summary#

About#

Description#

Its not a recipe#

How-to write a Reference#

Further Reading#

Discussions#

Summary#

About#

Description#

Boundaries#

How-to write Discussions#

Further Reading#

Document Templates#

Index Template#

reST Documentation#

How-to#

Reference#

First Example#

Discussion#

Further Reading#

Tutorial Template#

Design Principles#

Design UX Introduction#

Summary#

UX design process summary#

UX Design process detail#

Who#

What#

Why#

How#

When#

UX Design Tips#

Design with Tailwind css and Figma#

Figma Tutorial#

Tailwind Tutorials#

Style Guides#

Style Guide#

What#

How#

Why#

When#

Developer Styles#

Git#

Commit Message#

CHANGELOG#

reStructured Text Style#

Text Emphasis#