Remove old docs, add sphinx docs

Move info from old virtac/README.rst, virtac/FEEDBACK_SYSTEMS.rst into sphinx docs. Changed main README.rst to markdown and changed to work better with sphinx. Deleted some unused docs files. Updated conf.py to allow use of html images

Author: ptsOSL

README.md

@@ -3,35 +3,35 @@
 [![PyPI](https://img.shields.io/pypi/v/atip.svg)](https://pypi.org/project/atip)
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)
 
-# atip
 
-Accelerator Toolbox Interface for Pytac
+# ATIP - Accelerator Toolbox Interface for Pytac
 
-This is where you should write a short paragraph that describes what your module does,
-how it does it, and why people should use it.
+ATIP is an addition to  [Pytac](<https://github.com/DiamondLightSource/pytac>),
+a framework for controlling particle accelerators. ATIP adds a simulator to
+Pytac, which can be used and addressed in the same way as a real accelerator.
+
+ATIP enables the easy offline testing of high level accelerator
+controls applications, by either of two methods:
+
+* By replacing the real accelerator at the point where it is addressed by the
+  software, in the Pytac lattice object;
+
+* In a standalone application as a "virtual accelerator", publishing the same
+  control system interface as the live machine. At Diamond Light Source this
+  has been implemented with EPICS, and run on a different port to the
+  operational control system. So the only change required to test software is
+  to configure this EPICS port.
+
+The python implementation of
+[Accelerator Toolbox](<https://github.com/atcollab/at>) (pyAT) is used for the
+simulation.
 
 Source          | <https://github.com/DiamondLightSource/atip>
 :---:           | :---:
 PyPI            | `pip install atip`
+Docker          | `docker run ghcr.io/diamondlightsource/atip:latest`
 Documentation   | <https://diamondlightsource.github.io/atip>
+Installation    | <https://diamondlightsource.github.io/atip/tutorials/installation>
 Releases        | <https://github.com/DiamondLightSource/atip/releases>
 
-This is where you should put some images or code snippets that illustrate
-some relevant examples. If it is a library then you might put some
-introductory code here:
-
-```python
-from atip import __version__
-
-print(f"Hello atip {__version__}")
-```
-
-Or if it is a commandline tool then you might put some example commands here:
-
-```
-python -m atip --version
-```
-
 <!-- README only content. Anything below this line won't be included in index.md -->
-
-See https://diamondlightsource.github.io/atip for more detailed documentation.

README.rst

@@ -14,3 +14,4 @@ API
     :recursive:
 
     atip
+    virtac

docs/_api.rst

@@ -52,7 +52,7 @@
 ]
 
 # So we can use the ::: syntax
-myst_enable_extensions = ["colon_fence"]
+myst_enable_extensions = ["colon_fence", "html_image"]
 
 # If true, Sphinx will warn about all references where the target cannot
 # be found.

docs/atip.rst

@@ -6,5 +6,7 @@ Explanations of how it works and why it works that way.
 :maxdepth: 1
 :glob:
 
+explanations/implementation_details
+explanations/feedback_systems
 explanations/*
 ```

docs/conf.py

@@ -1,6 +1,5 @@
-================
-Feedback Systems
-================
+# Feedback Systems
+
 
 Currently supported "slow" feedback systems at Diamond are:
 
@@ -12,8 +11,7 @@ Currently supported "slow" feedback systems at Diamond are:
 In order to support these various feedback systems, the virtual accelerator
 makes several adjustments and additions to core ATIP functionality.
 
-Mirrored Records:
------------------
+## Mirrored Records:
 
 The ability to create mirror records is provided. A mirror record can take
 value(s) from one or more records as inputs and set its output dependent on
@@ -36,8 +34,7 @@ For more information on mirror records see docstrings of the classes in
 ``mirror_objects.py``, the relevant methods on ``ATIPServer``, and
 ``generate_mirrored_pvs`` in ``create_csv.py``.
 
-Masks:
-------
+## Masks:
 
 Masks are wrappers for existing functions to enable them to be addressed using
 a different syntax than normal. The types of masks are:
@@ -54,8 +51,7 @@ a different syntax than normal. The types of masks are:
    record object, ``.set(value)`` simply calls ``caput(stored_pv, value)``.
 
 
-Tune feedback
--------------
+## Tune feedback
 
 As mentioned above, the ``callback_offset`` class allows the tune feedback
 system to function exactly as it does on the live machine.