Improved project description, rearranged content for developers #41

noi-techpark · Feb 27, 2019 · 6ce4d48 · 6ce4d48
1 parent 081abdf
commit 6ce4d48
Show file tree

Hide file tree

Showing 11 changed files with 98 additions and 64 deletions.
diff --git a/source/appendices.rst b/source/appendices.rst
@@ -6,9 +6,9 @@ The following is the list of appendices.
 .. toctree::
    :caption: Appendices
    :numbered: 1
-   :maxdepth: 2
+   :maxdepth: 4
 
-   architecture
+   datasets
    guidelines
    glossary
    licenses

diff --git a/source/architecture.rst b/source/architecture.rst
@@ -1,7 +1,3 @@
-.. _architecture-odh:
-
-|ODH| Architecture
-==================
 
 The architecture of the |odh| is depicted in :numref:`arch-odh`, which
 shows its composing elements together with its main goal: To gather
@@ -14,7 +10,7 @@ data analysis to produce :term:`statistical graphics`.
 .. _arch-odh:
 
 .. figure::  /images/odh-architecture.png
-   :scale: 99%
+   :width: 99%
 
    The |odh| architecture with the components (top) and the data
    format used (bottom) during the data transformation.
@@ -136,10 +132,3 @@ Also part of the architecture, but not pictured in the diagram, is the
 :file:`persistence.xml` file, which contains the credentials and
 postgres configuration used by both the Reader and Writer.
 
-
-.. _dtp-env:
-
-Development, Testing, and Production Environments
--------------------------------------------------
-
-.. include:: dtp.rst
diff --git a/source/conf.py b/source/conf.py
@@ -91,7 +91,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This patterns also effect to html_static_path and html_extra_path
-exclude_patterns = ['replace.rst', 'dtp.rst', 'datasets', 'domains.rst']
+exclude_patterns = ['replace.rst', 'dtp.rst', 'datasets', 'domains.rst', 'architecture.rst'] 
 
 # The reST default role (used for this markup: `text`) to use for all
 # documents.

diff --git a/source/contribute.rst b/source/contribute.rst
@@ -101,8 +101,8 @@ tasks to be carried out:
    separate parts: :doc:`guidelines/platform` and
    :doc:`guidelines/database`.
 
-#. Understand the :doc:`architecture <architecture>` of both the |odh|
-   and |bdp|\.
+#. Understand the :ref:`architecture <architecture-odh>` of both the
+   |odh| and |bdp|\.
 #. Learn about the :ref:`dtp-env`.
 #. Install the necessary software on your local workstation (be it a
    physical workstation, a virtual machine, or a Docker instance),

diff --git a/source/datasets.rst b/source/datasets.rst
@@ -1,7 +1,9 @@
+
+.. _available_datasets:
+
 Datasets
 ========
 
-
 The goal of the |odh| Project is to make available datasets containing
 data about the South Tyrolean Ecosystem, to allow third parties to
 develop novel applications on top of them, consuming the exposed
@@ -11,16 +13,18 @@ different graphic formats like pie-charts, to far more complex
 applications that combine data from different datasets and correlate
 them in some useful way.
 
-.. note:: This page was last updated on |today|, hence all information
-   about the availability of datasets is correct as of this date. This
-   page will be updated in due time as soon as more material will be
-   made available.
+.. changed |today| to a static date 4 iaa
+   
+.. note:: This page was last updated on 15th January 2019, hence all
+   information about the availability of datasets is correct as of
+   this date. This page will be updated in due time as soon as more
+   material will be made available.
 
    This page will be soon removed, as all the information statically
    provided here will be in the near future be replaced by :ref:`the
    broker service <broker>`, which dynamically maintains the list.
 
-As seen in :numref:`domains`, data originate from different
+As seen in :numref:`domains-diagram`, data originate from different
 domains (Mobility, Tourism, and so on); they are gathered from sensors
 and packed within :strong:`datasets`. `Sensors` can be for example GPS
 devices installed on buses that send their real-time geographic

diff --git a/source/domains.rst b/source/domains.rst
@@ -1,31 +1,12 @@
-Project Overview
-================
-
-In this section you can find an overview of the |odh| Project and an
-introduction to the available `Domains`, `APIs`, and `Datasets`.
-
-.. _domains:
-
-.. figure:: /images/domain.png
-   :width: 80%
-
-   An overview of the |odh| Project.
-
-In a nutshell, the |odh| Project takes data from multiple domains
-(mobility, tourism, meteo), makes them available through the |odh|
-with the purpose to allow third party developers (or any interested
-user) to use them within their own projects, using the available APIs.
-
-.. _available_datasets:
-
-Domains with Available Datasets
--------------------------------
-
-This part has been moved :doc:`to its own section <datasets>`
-
-Available APIs
---------------
-
+..
+   In a nutshell, the |odh| Project takes data from multiple domains
+   (mobility, tourism, meteo), makes them available through the |odh|
+   with the purpose to allow third party developers (or any interested
+   user) to use them within their own projects, using the available APIs.
+
+The domains that are intended as sources for data served by the |odh| are
+depicted in :numref:`domains-diagram`.
+
 The :strong:`API` of a software contains the definition of methods and of
 their signatures, that can be invoked to retrieve data from the web
 services provided by the software itself. The signature of each method

diff --git a/source/guidelines.rst b/source/guidelines.rst
@@ -15,4 +15,5 @@ app
    guidelines/introduction
    guidelines/platform
    guidelines/database
+   guidelines/dtp
    contributors
diff --git a/source/dtp.rst → source/guidelines/dtp.rst b/source/dtp.rst → source/guidelines/dtp.rst
@@ -1,3 +1,7 @@
+.. _dtp-env:
+
+Development, Testing, and Production Environments
+-------------------------------------------------
 
 .. note:: Information in this section is still provisional!
 
@@ -7,7 +11,7 @@
 .. _dtp:
 
 .. figure:: /images/DTP.png
-   :scale: 99
+   :scale: 99%
 
    Diagram showing the development, testing, and production
    environments in the |odh| project.

diff --git a/source/index.rst b/source/index.rst
@@ -12,7 +12,6 @@ Welcome to |odh| Documentation Repository!
    :caption: Table of Contents
 
    Introduction & Project Overview <intro>
-   datasets
    contribute
    howto
    applist

diff --git a/source/intro.rst b/source/intro.rst
@@ -5,22 +5,74 @@
  Introduction
 ==============
 
-.. todo:: Here goes a not-so-detailed description of the project in a
-   few paragraphs: Its purpose, what can be find here etc, who is the
-   intended audience etc.
-
-
-This is the website of the |ODH| documentation repository, a collection of
-resources about the |odh| project. The website serves as the main
-resource portal for everyone interested in deploying apps based on
-:term:`datasets <dataset>` & :term:`API`\s provided by the |odh| team.
+This is the website of the |ODH| documentation, a collection of
+technical resources about the |odh| project. The website serves as the
+main resource portal for everyone interested in accessing the data or
+deploying apps based on :term:`datasets <dataset>` & :term:`API`\s
+provided by the |odh| team.
 
 The technical stuff is composed of:
 
 * Catalogue of available datasets.
-* How-tos.
-* API documentation.
+* How-tos, FAQs, and various tips and tricks for users.
 * Links to the full API documentation.
+* Resources for developers.
+
+For non-technical information about the |odh| project, please point 
+your browser to https://opendatahub.bz.it/.
+
+Project Overview
+================
+
+The |odh| project envisions the development and set up of a portal
+whose primary purpose is to offer a single access point to all (Open)
+Data from the region of South Tyrol, Italy, that are relevant for the
+economy sector and its actors. This will also allow everybody to
+utilise these data in all digital communication channels and build
+application on top of the data offered, be them either a :abbr:`PoC
+(Proof of Concept)` to explore new means or new field in which to use
+|odh| data, or novel and innovative services or software products
+built on top of the data. 
+
+.. _domains-diagram:
+
+.. figure:: /images/domain.png
+   :width: 99%
+
+   An overview of the |odh| Project.
+
+All the data within the |odh| will be easily accessible, preferring
+open interfaces and APIs which are built on existing standards like
+`The Open Travel Alliance <https://opentravel.org/>`_ (OTA), `The
+General Transit Feed Specification <https://gtfs.org/>`_ (GTFS),
+`Alpinebits <https://www.alpinebits.org/>`_.
+
+The |odh| team also strives to keep all data regularly updated, and
+use standard exchange formats for them like `Json
+<http://www.json.org/>`_ and the `Data Catalog Vocabulary
+<https://www.w3.org/TR/vocab-dcat/>`_ (DCAT).
 
+Depending on the development of the project and the interest of users,
+more standards and data formats might be supported in the future.
+
+
+.. _architecture-odh:
+
+|ODH| Architecture
+------------------
+
+.. include:: /architecture.rst
+
+.. _available-domains:
+
+Available Domains and APIs
+--------------------------
 
 .. include:: /domains.rst
+
+
+Available Datasets
+------------------
+
+The list of available datasets has been moved :doc:`to a dedicated page
+<datasets>`.
diff --git a/source/odh/static/odh.css b/source/odh/static/odh.css
@@ -5,6 +5,10 @@ body {
     font-family: Lato, Helvetica, Arial, sans-serif;
 }
 
+.wy-nav-content{
+    max-width: 1024px;    
+}
+
 .license {
     text-decoration: none;
     background-color: #EEEEEE;