Skip to content

Commit

Permalink
Merge pull request #218 from noi-techpark/issue-209-feedback-about-docs
Browse files Browse the repository at this point in the history 
Issue 209 feedback about docs
  • Loading branch information
@bertolla
bertolla committed May 11, 2021
2 parents f9bded1 + ad82abe commit 0cba89f
Show file tree
Hide file tree
Showing 20 changed files with 267 additions and 235 deletions.
144 changes: 144 additions & 0 deletions source/access-odh.rst
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,144 @@
.. _data-access:

Accessing the Open Data Hub
---------------------------

There are different modalities to access data that are provided by the
Open Data Hub, that are listed here. Currently, data from the
:strong:`Mobility` and :strong:`Tourism` domains can be accessed, both
from the command line and using a browser. Non-interactive access
using APIs is also available. Various dedicated tutorials are
available in the :ref:`howto-list` section; while in section
:ref:`getting-involved` you can find additional ways to interact with
the data and the Open Data Hub team. The remainder of this section describes
all the possibilities to access the Open Data Hub's datasets and their
content.


Browser access
~~~~~~~~~~~~~~

Accessing data in the Open Data Hub by using a browser is useful on
different levels: for the casual user, who can have a look at the
type and quality of data provided; for a developer, that can use
the :term:`REST API` implemented by the Open Data Hub or even check
if the results of his app are coherent with those retrieved with
the API; for everyone in order to get acquainted with the various
methods to retrieve data.

More in detail, these are the possibilities to interact with Open Data Hub's
data by using a browser:

.. panels::
:container: container-fluid pb-3
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2

Go to the :ref:`applist` section of the documentation,
particularly sub-sections :ref:`production-stage-apps` and
:ref:`beta-stage-apps`, and choose one of the web sites and
portals that are listed there. Each of them uses the data
gathered from one or more OPEN DATA HUB's datasets to display a
number of useful information. You can then see how data are
exposed and browse them.

---

In the same :ref:`applist` section, you can also check the list
of the :strong:`Alpha Stage Apps` and choose one of them that
you think you can expand, then get in touch with the authors to
suggest additional features or collaborate with them to discuss
its further development to improve it.

---

Access the `ODH Tourism data browser
<http://tourism.opendatahub.bz.it/>`_ and search for the Open
Data available in the Tourism domain. You can simply use those
data for your convenience, or you might even find a novel way to
exploit those data and use them in an app or portal you are
going to develop. A detailed howto is available:
:ref:`tourism-data-browser-howto` to help you getting acquainted
with the browser.

---

Go to the :strong:`Swagger interface` of the datasets in the
Tourism domain, located at
http://tourism.opendatahub.bz.it/swagger/ui/index to learn how
the REST APIs are built and how you can script them to fetch
data for your application. To get started, there is a dedicated
howto: :ref:`tourism-data-howto` that will guide you in the
first steps.

---

Access the :strong:`Swagger interface` of the datasets in the
Mobility domain, located at
https://mobility.api.opendatahub.bz.it/. Like in the case of the
tourism' Swagger interface, you can learn REST API call for that
domain and fetch data for your application. More possibilities
to interact with the Mobility domain datasets and the
description of the new APIv2 are described in the
:ref:`dedicated howto <get-started-mobility>`.

---

Open the :strong:`Analytics for Mobility` web page, at
https://analytics.opendatahub.bz.it/ This portal uses data in
the mobility domain to display various information about the
sensors, including their locations, what they measure, and
actual data in near-real time. You can retrieve data gathered by
the sensors directly from the dataset, in almost real-time.

---
:column: col-12 p-2

Open the `Open Data Hub Knowledge Graph Portal
<https://sparql.opendatahub.bz.it/>`_ where you can explore all
the data that are already available as a virtual knowledge
graph. Here you can check out some of the precooked query to see
and modify them to suit your needs with the help of W3C's
`SPARQL query language
<https://www.w3.org/TR/sparql11-overview/>`_; SPARQL can be used
also in the `Playground` to freely query the endpoint.

Programmatic access
~~~~~~~~~~~~~~~~~~~

Programmatic and non-interactive access to the Open Data Hub's dataset
is possible using any of the following methods made available
by the |odh| team.

.. panels::
:container: container-fluid

.. _ab-access:

AlpineBits client
^^^^
.. include:: /includes/AlpineBits.rst

----

.. _r-access:

Statistical Access with R
^^^^
.. include:: /includes/R.rst

---
.. _ninja api:

API
^^^^

.. include:: /includes/API.rst

---

.. _cli-access:

CLI access
^^^^

.. include:: /includes/CLI.rst
16 changes: 16 additions & 0 deletions source/changelog.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -90,3 +90,19 @@ documentation.

Add troubleshooting section to :ref:`R howto <howto-r>`.

.. changelog::
:version: 2021.05
:released: 31 May 2021

.. change::
:tags: Improvement
:tickets: 209

A lot of improvements have been added to the general structure
of the documentation, the most important being:

* reorder ToC and make some section more prominent
* made bash code snippets more usable
* made accessing methods more immediate to see

For more details, please check the reference.
2 changes: 1 addition & 1 deletion source/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@
# built documents.
#
# The short X.Y version.
version = u'2021.04'
version = u'2021.05'
# The full version, including alpha/beta/rc tags.
release = version

Expand Down
171 changes: 11 additions & 160 deletions source/datasets.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -106,152 +106,6 @@ At the date of writing, datasets in the :ref:`Mobility
<mobility-datasets>` and :ref:`Tourism <tourism-datasets>` domains are
available.

.. _data-access:

Accessing data in the Open Data Hub
-----------------------------------

There are different modalities to access data that are provided by the
Open Data Hub, that are listed here. Currently, data from the
:strong:`Mobility` and :strong:`Tourism` domains can be accessed, both
from the command line and using a browser. Non-interactive access
using APIs is also available. Various dedicated tutorials are
available in the :ref:`howto-list` section; while in section
:ref:`getting-involved` you can find additional ways to interact with
the data and the Open Data Hub team. The remainder of this section describes
all the possibilities to access the Open Data Hub's datasets and their
content.


.. dropdown:: Browser access
:title: font-weight-bold
:animate: fade-in-slide-down

Accessing data in the Open Data Hub by using a browser is useful on
different levels: for the casual user, who can have a look at the
type and quality of data provided; for a developer, that can use
the :term:`REST API` implemented by the Open Data Hub or even check
if the results of his app are coherent with those retrieved with
the API; for everyone in order to get acquainted with the various
methods to retrieve data.

More in detail, these are the possibilities to interact with Open Data Hub's
data by using a browser:

.. panels::
:container: container-fluid pb-3
:column: col-lg-4 col-md-4 col-sm-6 col-xs-12 p-2

Go to the :ref:`applist` section of the documentation,
particularly sub-sections :ref:`production-stage-apps` and
:ref:`beta-stage-apps`, and choose one of the web sites and
portals that are listed there. Each of them uses the data
gathered from one or more OPEN DATA HUB's datasets to display a
number of useful information. You can then see how data are
exposed and browse them.

---

In the same :ref:`applist` section, you can also check the list
of the :strong:`Alpha Stage Apps` and choose one of them that
you think you can expand, then get in touch with the authors to
suggest additional features or collaborate with them to discuss
its further development to improve it.

---

Access the `ODH Tourism data browser
<http://tourism.opendatahub.bz.it/>`_ and search for the Open
Data available in the Tourism domain. You can simply use those
data for your convenience, or you might even find a novel way to
exploit those data and use them in an app or portal you are
going to develop. A detailed howto is available:
:ref:`tourism-data-browser-howto` to help you getting acquainted
with the browser.

---

Go to the :strong:`Swagger interface` of the datasets in the
Tourism domain, located at
http://tourism.opendatahub.bz.it/swagger/ui/index to learn how
the REST APIs are built and how you can script them to fetch
data for your application. To get started, there is a dedicated
howto: :ref:`tourism-data-howto` that will guide you in the
first steps.

---

Access the :strong:`Swagger interface` of the datasets in the
Mobility domain, located at
https://mobility.api.opendatahub.bz.it/. Like in the case of the
tourism' Swagger interface, you can learn REST API call for that
domain and fetch data for your application. More possibilities
to interact with the Mobility domain datasets and the
description of the new APIv2 are described in the
:ref:`dedicated howto <get-started-mobility>`.

---

Open the :strong:`Analytics for Mobility` web page, at
https://analytics.opendatahub.bz.it/ This portal uses data in
the mobility domain to display various information about the
sensors, including their locations, what they measure, and
actual data in near-real time. You can retrieve data gathered by
the sensors directly from the dataset, in almost real-time.

---
:column: col-12 p-2

Open the `Open Data Hub Knowledge Graph Portal
<https://sparql.opendatahub.bz.it/>`_ where you can explore all
the data that are already available as a virtual knowledge
graph. Here you can check out some of the precooked query to see
and modify them to suit your needs with the help of W3C's
`SPARQL query language
<https://www.w3.org/TR/sparql11-overview/>`_; SPARQL can be used
also in the `Playground` to freely query the endpoint.

.. dropdown:: Programmatic access
:title: font-weight-bold
:animate: fade-in-slide-down

Programmatic and non-interactive access to the Open Data Hub's dataset
is possible using any of the following methods made available
by the |odh| team.

.. panels::
:container: container-fluid

.. _ninja api:

.. dropdown:: API

.. include:: /includes/API.rst

---

.. _cli-access:

.. dropdown:: CLI access

.. include:: /includes/CLI.rst

----

.. _ab-access:

.. dropdown:: AlpineBits client

.. include:: /includes/AlpineBits.rst

----

.. _r-access:

.. dropdown:: Statistical Access with R

.. include:: /includes/R.rst

.. _license-json-records:

License of the JSON Responses
Expand Down Expand Up @@ -340,16 +194,15 @@ Datasets in the Mobility Domain
.. versionchanged:: 2020.09 added dropdowns to the list of datasets to
improve usability

.. figure:: /images/Mobility-domain.png
:align: right
:scale: 120 %

The dataset in the Mobility Domain at a glance.

This section contains information about the datasets in the Mobility
Domain and how to access them using the API that the Open Data Hub
team developed and made available.

.. figure:: /images/Mobility-domain.png
:align: center

The dataset in the Mobility Domain at a glance.

.. note:: Recall that the API v1 for the Mobility Domain is now :strong:`deprecated`.

The description of each dataset includes the following information:
Expand Down Expand Up @@ -492,17 +345,15 @@ for e-cars.
Datasets in the Tourism Domain
------------------------------

.. figure:: /images/Tourism-domain.png
:align: right
:scale: 120 %

The dataset in the Tourism Domain at a glance.


This section contains information about the dataset in the Tourism
Domain and how to access them using the API that the Open Data Hub
team developed and made available.

.. figure:: /images/Tourism-domain.png
:align: center

The dataset in the Tourism Domain at a glance.

Datasets presented here are related to all kind of touristic
activities in South Tyrol. By exploring this domain, it is possible to
find information about winter and summer offers from local touristic
Expand Down Expand Up @@ -663,4 +514,4 @@ Datasets in Other Domains

.. odh vkg km
.. include:: kg.rst
.. include:: /includes/kg.rst
2 changes: 1 addition & 1 deletion source/guidelines.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,4 +18,4 @@ contracted to write code or apps for the |odh| project (|odh| Core Hacker)
/guidelines/database.rst
/guidelines/dtp.rst
/guidelines/authentication.rst
/contributors.rst
/guidelines/contributors.rst

0 comments on commit 0cba89f

Please sign in to comment.