DOC Restructured digital twins sections, fixed warnings and issues th…

…roughout, added variou scommentary and images

.gitignore

@@ -105,3 +105,8 @@ venv.bak/
 
 # jetbrains ides
 .idea/
+
+# Sphinx related files
+docs/source/doxyoutput/
+docs/source/library_api/
+docs/build/

docs/source/digital_twins.rst

@@ -0,0 +1,57 @@
+.. _digital_twins:
+
+=============
+Digital Twins
+=============
+
+A digital twin is a virtual representation of a real life being - a physical asset like a wind turbine or car - or even
+a human.
+
+There are three reasons why you might want to create a digital twin:
+    - Monitoring
+    - Prediction
+    - Optimisation
+
+On its own, a digital twin can be quite useful. For example, a twin might embody an AI-based analysis to predict power
+output of a turbine.
+
+.. figure:: images/digital_twin_component_basic.svg
+    :width: 400px
+    :align: center
+    :figclass: align-center
+    :alt: A digital twin component
+
+    A digital twin consists of some kind of analysis or processing task, which could be run many times per second, or
+    daily, down to occasionally or sometimes only once (the same as a "normal" analysis).
+
+Coupling digital twins is generally even more useful. You might wish to couple your turbine twin with a representation
+of the local power grid, and a representation of a factory building to determine power demand... enabling you to
+optimise your factory plant for lowest energy cost whilst intelligently selling surplus power to the grid.
+
+.. figure:: images/digital_twin_hierarchy.svg
+    :width: 350px
+    :align: center
+    :figclass: align-center
+    :alt: Hierarchy of digital twins
+
+    A hierarchy of digital twins. Each blue circle represents a twin, coupled to its neighbours. Yellow nodes are where
+    schema are used to connect twins.
+
+
+.. _gemini_principles:
+
+Gemini Principles
+=================
+
+The Gemini Principles have been derived by the
+`Centre for Digital Built Britain (CDBB) <https://www.cdbb.cam.ac.uk/system/files/documents/TheGeminiPrinciples.pdf>`_.
+We strongly recommend you give them a read if embarking on a digital twins project.
+
+The aim of **twined** is to enable the following principles. In particular:
+
+#. Openness (open-source project to create schema for twins that can be run anywhere, anywhen)
+#. Federation (encouraging a standardised way of connecting twins together)
+#. Security (making sure schemas and data can be read safely)
+#. Public Good (see our nano-rant about climate change in :ref:`reason_for_being`)
+
+

docs/source/index.rst

@@ -1,3 +1,9 @@
+.. ATTENTION::
+    This library is in very early stages. Like the idea of it? Please
+    `star us on GitHub <https://github.com/octue/twined>`_ and contribute via the
+    `issues board <https://github.com/octue/twined/issues>`_ and
+    `roadmap <https://github.com/octue/twined/projects/1>`_.
+
 .. image:: https://codecov.io/gh/octue/twined/branch/master/graph/badge.svg
   :target: https://codecov.io/gh/octue/twined
   :alt: Code coverage
@@ -8,70 +14,52 @@
   :align: right
 
 ======
-twined
+Twined
 ======
 
-**twined** is a library to help digital twins talk to one another.
-
+**twined** is a library to help :ref:`digital_twins` talk to one another.
 
 .. epigraph::
-   "Twined" [t-why-nd] - encircled, twisted together, interwoven
-
-
-.. ATTENTION::
-    This library is in very early stages. Like the idea of it? Please
-    `star us on GitHub <https://github.com/octue/twined>`_ and contribute via the
-    `issues board <https://github.com/octue/twined/issues>`_ and
-    `roadmap <https://github.com/octue/twined/projects/1>`_.
-
-
-.. _digital_twins:
-Digital Twins
-=============
+   *"Twined" [t-why-nd] ~ encircled, twisted together, interwoven*
 
 A digital twin is a virtual representation of a real life being - a physical asset like a wind turbine or car - or even
-a human.
+a human. Like real things, digital twins need to interact, so can be connected together, but need a common communication
+framework to do so. This is what is provided by **twined**.
 
-.. figure:: images/digital_twin_hierarchy.png
-    :width: 500px
+.. figure:: images/digital_twin_hierarchy.svg
+    :width: 350px
     :align: center
     :figclass: align-center
     :alt: Hierarchy of digital twins
 
-    A hierarchy of digital twins. Each blue circle represents a twin, coupled to its neighbours. Yellow nodes are where
-    schema are used to connect twins.
-
-There are three reasons why you might want to create a digital twin:
-    - Monitoring
-    - Prediction
-    - Optimisation
-
-On its own, a digital twin can be quite useful. For example, a twin might embody an AI-based analysis to predict power
-output of a turbine.
-
-Coupling digital twins is generally even more useful. You might wish to couple your turbine twin with a representation
-of the local power grid, and a representation of a factory building to determine power demand... enabling you to
-optimise your factory plant for lowest energy cost whilst intelligently selling surplus power to the grid.
+    Digital twins connected in a hierarchy. Each blue circle represents a twin, coupled to its neighbours.
+    Yellow nodes are where schema are used to connect twins.
 
 
 .. _aims:
+
 Aims
 ====
 
-**twined** provides a toolkit to help create and validate "schema" - descriptions of a digital twin, what data it
+**twined** provides a toolkit to help create and validate ":ref:`schema`" - descriptions of a digital twin, what data it
 requires, what it does and how it works.
 
 The goals of **twined** are as follows:
     - Provide a clear framework for what a digital twin schema can and/or must contain
     - Provide functions to validate incoming data against a known schema
-    - Provide tools to create schema describing what you require
-    - Provide a function to check that a schema itself is valid
+    - Provide functions to check that a schema itself is valid
+    - Provide (or direct you to) tools to create schema describing what you require
 
-Using schema, we can describe how digital twins connect and interact... building them together in hierarchies and
-networks. You'll find an in depth description in the :ref:`schema` section.
+Using :ref:`schema`, we can describe how digital twins connect and interact... building them together in hierarchies and
+networks.
+
+The scope of **twined** is not large. Many other libraries will deal with hosting and deploying digital twins, still
+more will deal with the actual analyses done within them. **twined** purely deals with parsing and checking the
+information exchanged.
 
 
 .. _reason_for_being:
+
 Raison d'etre
 =============
 
@@ -86,6 +74,7 @@ develop a wider ecosystem.
 
 
 .. _uses:
+
 Uses
 =====
 
@@ -104,6 +93,7 @@ building digital twins using **twined**.
 
 
 .. _life_choices:
+
 Life Choices
 ============
 
@@ -116,12 +106,13 @@ and are willing to consider sponsorship of development and maintenance of that l
 
 
 .. toctree::
-   :maxdepth: 1
+   :maxdepth: 2
    :hidden:
 
    self
-   installation
+   digital_twins
    schema
+   installation
    examples
    license
    version_history

docs/source/installation.rst

@@ -4,23 +4,26 @@
 Installation
 ============
 
-**twined** is available on pypi, so installation into your python virtual environment is dead simple:
+**twined** is available on `pypi <https://pypi.org/>`_, so installation into your python virtual environment is dead
+simple:
 
-.. code-block::
+.. code-block:: py
 
     pip install twined
 
-Don't have a virtual environment with pip? You probably should! pyenv is your friend. Google it.
+Don't have a virtual environment with pip? You probably should! ``pyenv`` is your friend. Google it.
 
 
 .. _compilation:
+
 Compilation
 ============
 
 There is presently no need to compile **twined**, as it's written entirely in python.
 
 
 .. _third_party_library_installation:
+
 Third party library installation
 ================================
 
@@ -29,6 +32,7 @@ automatically installed during the installation above.
 
 
 .. _third_party_build_requirements:
+
 Third party build requirements
 ==============================
 

docs/source/schema.rst

@@ -12,9 +12,9 @@ Requirements of digital twin schema
 
 A *schema* defines a digital twin, and has multiple roles. It:
 
-#. defines what data is required by a digital twin, in order to run
-#. defines what data will be returned by the twin following a successful run
-#. defines the formats of these data, in such a way that incoming data can be validated
+#. Defines what data is required by a digital twin, in order to run
+#. Defines what data will be returned by the twin following a successful run
+#. Defines the formats of these data, in such a way that incoming data can be validated
 
 If this weren't enough, the schema:
 
@@ -24,17 +24,18 @@ If this weren't enough, the schema:
 #. Must be searchable/indexable
 
 Fortunately for digital twin developers, many of these requirements have already been seen for data interchange formats
-developed for the web. **twined** uses `JSON` and `JSONSchema` to interchange data between digital twins. If you're not
-already familiar with JSONSchema (or wish to know why **twined** uses `JSON` over the seemingly more appropriate `XML`
-standard), see :ref:`introducing_json_schema`.
+developed for the web. **twined** uses ``JSON`` and ``JSONSchema`` to interchange data between digital twins.
+
+If you're not already familiar with ``JSONSchema`` (or wish to know why **twined** uses ``JSON`` over the seemingly more
+appropriate ``XML`` standard), see :ref:`introducing_json_schema`.
 
 
 .. _specifying_a_framework:
 Specifying a framework
 ======================
 
-We cannot simply expect many developers to create digital twins with a `JSONSchema` then to be able to connect them all
-together. **twined** makes things slightly more specific
+We cannot simply expect many developers to create digital twins with a ``JSONSchema`` then to be able to connect them all
+together. **twined** makes things slightly more specific.
 
 
 .. toctree::