Added placeholder for Sphinx documentation

Pipfile

@@ -0,0 +1,28 @@
+[[source]]
+name = "pypi"
+url = "https://pypi.org/simple"
+verify_ssl = true
+
+[packages]
+docker = "*"
+jinja2 = "*"
+jsonschema = "*"
+m2r = "*"
+PyYAML = "*"
+redis = "~=2.10.6"
+Sphinx = "*"
+sphinx_rtd_theme = "*"
+sphinxcontrib-websupport = "*"
+
+[dev-packages]
+doc8 = "*"
+pylint = "*"
+pytest = "*"
+pytest-pylint = "*"
+pytest-codestyle = "*"
+pytest-pydocstyle = "*"
+pytest-cov = "*"
+sphinx-autobuild = "*"
+
+[requires]
+python_version = "3.6"

demos/01_sdp_states/README.md

@@ -1,4 +1,4 @@
-# SIP Demo: Monitoring and Control of the state of SDP
+# Demo 1: Monitoring and Control of the state of SDP
 
 ## 1  Introduction
 
@@ -189,7 +189,7 @@ As shown in the Figure below, these are light-weight prototypes of a number
 of the Execution Control, Tango Control and Platform services identified in
 the SDP architecture.
 
-![Services & Components](figures/services-components.png)
+![Services & Components](figures/services-components.png "")
 
 ### 3.2  Monitoring and Control of SDP
 

demos/02_running_a_workflow/README.md

@@ -1,4 +1,4 @@
-# SIP Demo: Running a workflow
+# Demo 2: Running a workflow
 
 ## 1.  Introduction
 

docs/Makefile

@@ -0,0 +1,19 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line.
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = src
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/PULL_REQUEST_TEMPLATE.md

@@ -1,23 +1,43 @@
-<!-- Provide a general summary of your changes in the Title above! -->
+<!-- The title in the field above should: -->
+<!--   1. Start with the JIRA ticket number (if possible) -->
+<!--   2. Provide a short summary of the key change or changes for this PR -->
 
-## Description:
-<!-- Describe your changes in more detail. If the change fixes an issue or is 
-related to a JIRA ticket, please refer to that here. -->
+# Description
+
+<!-- Describe your changes in more detail in this section. -->
+<!-- Describe what was changed and why, this does not need to be a long -->
+<!-- description but should help the reviewer know what you have done. -->
+
+## Testing instructions
 
-## Testing instructions:
 <!-- Describe how the code in the PR can be tested. -->
-<!-- Include details of the testing environment, set up and the tests that can be run. -->
+
+<!-- If all tests are already being run on the CI environment it is -->
+<!-- to simply describe where to find the test output relevant this change. -->
+<!-- If the change is not yet tested by the CI, please add instructions -->
+<!-- so that the reviewer knows how to verify the change in the PR. -->
 
 ## Types of changes
-<!-- What types of changes does this PR introduce? Put an 'x' in all of the boxes that apply. -->
-- [ ] Bug fix (non-breaking change that fixes an issue)
-- [ ] New feature (non-breaking change that adds functionality)
-- [ ] Breaking change (fix or feature that would cause existing functionality to change)
 
-## Checklist:
-<!-- Go over all of the following points and put and 'x' in the boxes that apply. -->
+<!-- What types of changes does this PR introduce? -->
+<!-- Put an 'x' in all of the boxes that apply. -->
+
+- [ ] New feature
+- [ ] Refactor
+- [ ] Bug fix
+- [ ] Documentation update
+- [ ] Breaking change
+- [ ] Non-breaking change
+
+## Checklist
+
+<!-- Put and 'x' in the boxes that apply. -->
+
+*(Please also refer to the [definition of done](https://bit.ly/ska_dod)
+in the SKA developer guidelines)*
+
 - [ ] The code follows the code style of this project.
-- [ ] The changes require a documentation update.
 - [ ] Documentation has been updated accordingly.
-- [ ] Tests cover all changes in this PR.
+- [ ] Tests cover changes in this PR (75% - 90% coverage).
+- [ ] Tests have be added to the CI script.
 - [ ] All new and existing tests passed.

docs/README.md

@@ -1,4 +1,37 @@
 # SIP Documentation
 
-Placeholder for any documentation, or technical notes related to SIP code
-which we choose to keep in the code repo rather than on Confluence. 
+This folder contains documentation and technical notes related to SIP code
+which we choose to keep in the code repository (rather than on Confluence).
+
+## Building Sphinx documentation
+
+Documentation is build automatically by the CI/CD **(TODO!)** script on pushes
+to the Github repository. It can also be build manually using the
+following commands (this assumes all dependencies have been installed -
+eg. `pipenv shell`!):
+
+Building the HTML documentation is as simple as running the following command
+from the `docs/` folder.
+
+```bash
+make html
+```
+
+This will render HTML documentation into the `docs/build/html` directory. To
+view these open `docs/build/html/index.html` in a web browser.
+
+If developing documentation the
+[`sphinx-autobuild`](https://github.com/GaretJax/sphinx-autobuild) Python
+package can also be very useful. This will rebuild the documentation
+automatically every time a change is made and serve it at the address
+<http://localhost:8000/>. If using the provided `pipenv`, this tool is already
+installed and can be used with the following command, run from the top level
+repository directory:
+
+```bash
+sphinx-autobuild docs/src docs/build/html
+```
+
+### Publishing to [`Read the Docs`](https://readthedocs.org/)
+
+...

docs/src/api.rst

@@ -0,0 +1,38 @@
+.. API
+
+.. toctree::
+    :maxdepth: 2
+
+API
+***
+
+Configuration Database
+======================
+
+SDP State
+---------
+
+.. automodule:: sip_config_db.states.sdp_state
+   :members:
+   :inherited-members:
+
+Service States
+--------------
+
+.. automodule:: sip_config_db.states.service_state
+   :members:
+
+Services
+--------
+
+.. automodule:: sip_config_db.states.service_state
+   :members:
+
+Utility modules
+---------------
+
+.. automodule:: sip_config_db.utils.datetime_utils
+   :members:
+
+.. automodule:: sip_config_db.utils.generate_sbi_config
+   :members:

docs/src/background.rst

@@ -0,0 +1,7 @@
+.. Background
+
+.. toctree::
+    :maxdepth: 2
+
+Background
+**********