From 1a02838bbf6fb2b457ce1e432838bc6984eccaa4 Mon Sep 17 00:00:00 2001
From: Steve Crouch <s.crouch@software.ac.uk>
Date: Wed, 27 Feb 2019 09:57:22 +0000
Subject: [PATCH] Retitle admin guide based on roles, add release notes to top
of docs
---
docs/source/conf.py | 7 ++
docs/source/guide_administrator.rst | 20 ++++--
docs/source/guide_developer.rst | 5 ++
docs/source/guide_user.rst | 9 +++
docs/source/index.rst | 4 +-
docs/source/ref_applications_api.rst | 101 +++++++++++++++++++++++++++
6 files changed, 137 insertions(+), 9 deletions(-)
create mode 100644 docs/source/ref_applications_api.rst
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 8199c71..e42ae97 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -121,6 +121,13 @@ html_static_path = ['_static']
#
# html_sidebars = {}
+# Add following as a header for each rst file
+rst_prolog = """
+.. note:: This is a public alpha release, and therefore features and functionality may change and the software and documentation may contain technical bugs or other issues. If you discover any issues please consider registering a `GitHub issue`_.
+
+.. _`GitHub issue`: https://github.com/PEDASI/PEDASI/issues
+"""
+
# -- Options for HTMLHelp output ---------------------------------------------
diff --git a/docs/source/guide_administrator.rst b/docs/source/guide_administrator.rst
index f4fb934..301c7de 100644
--- a/docs/source/guide_administrator.rst
+++ b/docs/source/guide_administrator.rst
@@ -8,11 +8,17 @@ PEDASI Administration Guide
:caption: Contents:
-.. note:: Please read the :ref:`User Guide<guide_user>` first to give you an overview of the PEDASI platform before reading this guide.
+.. note:: Please read the :ref:`User Guide<guide_user>` first to give you an overview of the PEDASI platform and how to use its features before reading this guide.
-Deploying PEDASI in Production
-------------------------------
+Purpose
+-------
+
+This guide is for System Administrators aiming to deploy a PEDASI instance, and Data or Application Providers wanting to add, update, or remove data sources or applications within a PEDASI instance.
+
+
+System Administrators: Deploying PEDASI in Production
+-----------------------------------------------------
Overview
^^^^^^^^
@@ -59,8 +65,8 @@ Deployment
^^^^^^^^^^
-Managing Data Sources
----------------------
+Data Providers: Managing Data Sources
+-------------------------------------
Adding a Data Source
@@ -79,8 +85,8 @@ Approving Data Access Requests
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Managing Applications
----------------------
+Application Providers: Managing Applications
+--------------------------------------------
Adding an Application
diff --git a/docs/source/guide_developer.rst b/docs/source/guide_developer.rst
index 7e1cf82..faf0865 100644
--- a/docs/source/guide_developer.rst
+++ b/docs/source/guide_developer.rst
@@ -11,6 +11,11 @@ PEDASI Developer Guide
.. note:: Please read the :ref:`User Guide<guide_user>` first to give you an overview of the PEDASI platform before reading this guide.
+Purpose
+-------
+
+This guide is for application developers wanting to understand how to set up a development environment for PEDASI and develop PEDASI applications.
+
Deploying PEDASI for Development
--------------------------------
diff --git a/docs/source/guide_user.rst b/docs/source/guide_user.rst
index 4785d47..21e7a55 100644
--- a/docs/source/guide_user.rst
+++ b/docs/source/guide_user.rst
@@ -8,6 +8,15 @@ PEDASI User Guide
:caption: Contents:
+.. include:: release_note.rst
+
+
+Purpose
+-------
+
+This guide is for PEDASI users who want to understand the PEDASI platform and how to use its features.
+
+
User Model
----------
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 34e1796..34a5e68 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -1,7 +1,7 @@
.. _doc-index:
-PEDASI
-======
+PEDASI v0.9.0
+=============
.. toctree::
:maxdepth: 2
diff --git a/docs/source/ref_applications_api.rst b/docs/source/ref_applications_api.rst
new file mode 100644
index 0000000..497e73c
--- /dev/null
+++ b/docs/source/ref_applications_api.rst
@@ -0,0 +1,101 @@
+.. _ref_applications_api:
+
+Applications API Reference
+==========================
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+
+.. note:: Please read the :ref:`Developer Guide<guide_developer>` first before reading this reference.
+
+
+Overview
+--------
+
+This document provides a schema reference to the PEDASI Applications API which is used by third-party applications to request data, metadata, or provenance records from a PEDASI instance and its data sources.
+
+
+Using the API
+-------------
+
+
+API Endpoints
+^^^^^^^^^^^^^
+
+
+GET /api/datasources/
+^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+ TODO
+Retrieves the list of all data sources known to PEDASI, that the authenticated user has the ability to see. This will include some sources which they are unable to use, but have not had their details hidden.
+
+
+GET /api/datasources/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves the PEDASI metadata for a given data source, if the authenticated user has the ability to see it.
+
+
+GET /api/datasources/<int>/metadata/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+Any supported by data source API
+Retrieves metadata via an API query to a data source. The authenticated user must have permission to use the given data source.
+
+E.g. A HyperCat catalogue
+
+
+GET /api/datasources/<int>/metadata/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+GET /api/datasources/<int>/metadata/<URI>/ (maybe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves metadata for a single dataset contained within the source via an API query to the data source. The authenticated user must have permission to use the given data source.
+
+E.g. An entry within a HyperCat catalogue
+
+
+GET /api/datasources/<int>/data/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+Any supported by data source API
+In the case where a data source represents a single dataset, retrieve the dataset via an API query to the data source. The authenticated user must have permission to use the given data source.
+
+If the data source does not represent a single dataset, error.
+
+
+GET /api/datasources/<int>/data/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+GET /api/datasources/<int>/data/<URI>/ (maybe)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Params:
+In the case where a data source represents multiple datasets, retrieve a single dataset via an API query to the data source. The authenticated user must have permission to use the given data source.
+
+If the data source represents a single dataset, error.
+
+
+GET /api/datasources/<int>/prov/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Params:
+TODO
+Retrieve all PROV records related to a single data source.
+
+
+GET /api/datasources/<int>/prov/<int>/
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieve a single PROV record related to a the data source.
+
+
+References
+----------
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`
--
GitLab