Merge pull request #215 from noi-techpark/issue-208-feedback-howto

Issue 208 feedback howto

source/changelog.rst

@@ -55,7 +55,23 @@ documentation.
       sent to third party.
 
    .. change::
-      :tags: New Feature
+      :tags: Improvement
       :tickets: 208
 
+      * Replace tabs in the howto list with subsections.
+      * Remove the mobility howto for deprecated API v1.
+      * Reduce size of images in howtos and align them if layout
+        allows.
+
+   .. change::
+      :tags: Bugfix
+      :tickets: 208
+
+      Add correct images to `How to Access Analytics Data in the
+      Mobility Domain` howto.
+
+   .. change::
+      :tags: New Feature
+      :tickets: 204
+
       New Howto: :ref:`howto-r`

source/howto.rst

@@ -6,71 +6,90 @@ List of HOWTOs
 .. versionchanged:: 2020.10 Panels layout was replaced by tabs in the
    howto list.
 
+.. versionchanged:: 2021:04 Replace tabs with (sub-)sections.
+.. versionchanged:: 2021:04 Remove howto for API v1.
+.. versionchanged:: 2021:04 Resize images in all howtos.
+
 This page contains the list of available howtos, divided into
 areas. The list of howtos, together with a short description is
 available here:
 
-.. tabbed:: Mobility
-
-   #. :doc:`/howto/mobility/getstarted` Getting started with the
-      new API v2.
-   #. :doc:`/howto/mobility/mobility`. Since the APIs are very
-      generic, directions contained in this howto can be applied to
-      any dataset of the mobility domain.
-   #. :doc:`/howto/mobility/mobilityanalytics`. This howto guides you in
-      browse and query data produces from the sensors used in
-      the mobility domain.
-
-.. tabbed:: Tourism
-
-   #. :doc:`/howto/tourism/getstarted` Description of how to
-      access and manipulate data, the input data used, and the
-      various filters available in the Tourism domain.
-   #. :doc:`/howto/tourism/browse` Access to the open data
-      provided within the Tourism domain.
-   #. :doc:`/howto/tourism/tips` Mini howtos, tricks&tips, and
-      use cases for data in the Tourism domain.
-   #. :doc:`howto/tourism/alpinebits` access AlpineBits data
-
-.. tabbed:: Miscellaneous
-
-   #. :doc:`/howto/authentication` Access to data that are not yet
-      open (mostly for internal use).
-
-   #. :doc:`/howto/development` Set up your workstation to develop for
-      Open Data Hub--This tutorial is still in development and not so
-      useful at the moment!
-
-   #. :doc:`/howto/postman` Setup of Postman, a popular API
-      development environment, to access data from the Open Data Hub.
-
-   #. :doc:`/howto/noievents` Create and modify NOI events directly
-      from the Open Data Hub portal.
-
-   #. :doc:`/howto/webcomponents` share your Web Components with Open
-      Data Hub team
-
-   #. :doc:`/howto/sparql-endpoint` query |odh| datasets using W3C's
-      Query Language. 
-
-   #. :doc:`/howto/r-howto`  query |odh| datasets using R and its
-      SPARQL library.
+Mobility
+--------
+
+
+#. :doc:`/howto/mobility/getstarted` Getting started with the
+   new API v2.
+#. :doc:`/howto/mobility/mobilityanalytics` This howto guides you in
+   browse and query data produces from the sensors used in
+   the mobility domain.
+#. How to access e-Charging Stations Data? This howto is
+   |deprecated| and has been removed, please refer to
+   :doc:`/howto/mobility/getstarted` if you are interested in
+   accessing the mobility dataset.
 
 .. toctree::
    :maxdepth: 1
    :hidden:
 
    howto/mobility/getstarted
-   howto/mobility/mobility
    howto/mobility/mobilityanalytics
+
+Tourism
+-------
+
+#. :doc:`/howto/tourism/getstarted` Description of how to
+   access and manipulate data, the input data used, and the
+   various filters available in the Tourism domain.
+#. :doc:`/howto/tourism/browse` Access to the open data
+   provided within the Tourism domain.
+#. :doc:`/howto/tourism/tips` Mini howtos, tricks&tips, and
+   use cases for data in the Tourism domain.
+#. :doc:`howto/tourism/alpinebits` access AlpineBits data
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
    howto/tourism/getstarted
    howto/tourism/browse
-   howto/authentication
-   howto/development
-   howto/postman
-   howto/noievents
    howto/tourism/tips
-   howto/webcomponents
    howto/tourism/alpinebits
-   howto/sparql-endpoint
-   howto/r-howto
+
+Generic HOWTOs
+--------------
+
+#. :doc:`/howto/generic/authentication` Access to data that are not yet
+   open (mostly for internal use).
+
+#. :doc:`/howto/generic/development` Set up your workstation to develop for
+   Open Data Hub--This tutorial is still in development and not so
+   useful at the moment!
+
+#. :doc:`/howto/generic/postman` Setup of Postman, a popular API
+   development environment, to access data from the Open Data Hub.
+
+#. :doc:`/howto/generic/noievents` Create and modify NOI events directly
+   from the Open Data Hub portal.
+
+#. :doc:`/howto/generic/webcomponents` share your Web Components with Open
+   Data Hub team
+
+#. :doc:`/howto/generic/sparql-endpoint` query |odh| datasets using W3C's
+   Query Language.
+
+#. :doc:`/howto/generic/r-howto`  query |odh| datasets using R and its
+   SPARQL library.
+
+
+.. toctree::
+   :maxdepth: 1
+   :hidden:
+
+   howto/generic/authentication
+   howto/generic/development
+   howto/generic/postman
+   howto/generic/noievents
+   howto/generic/webcomponents
+   howto/generic/sparql-endpoint
+   howto/generic/r-howto

source/howto/authentication.rst → source/howto/generic/authentication.rst

@@ -48,7 +48,8 @@ respectively, as shown in :numref:`token-request`.
 
 .. _token-request:
 .. figure:: /images/token-request.png
-   :width: 80%
+   :scale: 33%
+   :align: center
 
    Request a new OAuth2 token.
 
@@ -62,10 +63,10 @@ parameter: You must use prefix the authentication token with the
 :strong:`Bearer` string, followed by an empty space, then by the
 token.
 
-
 .. _oauth-success:
 .. figure:: /images/emobility-200.png
-   :width: 80%
+   :scale: 33%
+   :align: center
 
    A successful call to a method requiring authentication.
 
@@ -75,8 +76,10 @@ shows), or use an invalid token, you will receive an :strong:`401 -
 Unauthorized` HTTP response.
 
 .. _oauth-failure:
+
 .. figure:: /images/emobility-401.png
-   :width: 80%
+   :scale: 33%
+   :align: center
 
    A failed call to a method requiring authentication.
 
@@ -86,7 +89,7 @@ Open a shell on your workstation and use a tool like :command:`curl`
 or :command:`wget`, with the appropriate options:
 
 .. option:: -X
-	       
+
    Specify the request method (GET)
 
 .. option:: --header, -H
@@ -96,7 +99,7 @@ or :command:`wget`, with the appropriate options:
 Note that the :option:`--header` option is used twice: The first to
 receive the answer in :strong:`text/html` format, the second to
 provide the credentials required to access protected content.
-   
+
 API calls can be done using a tool like :command:`curl` or
 :command:`wget`, with the same :option:`-X` and :option:`--header`
 option used twice: The first to require the format of the response,

source/howto/development.rst → source/howto/generic/development.rst

@@ -1,6 +1,3 @@
-make html
-.. geobank #10
-
 .. _development:
 
 How to set up your local Development Environment?
@@ -16,8 +13,6 @@ This tutorial is divided into three parts:
 #. Services configuration
 #. Troubleshooting
 
-.. warning:: This tutorial is still work in progress and is largely incomplete!
-
 
 Software Installation
 ---------------------

source/howto/noievents.rst → source/howto/generic/noievents.rst

@@ -20,8 +20,9 @@ Go to http://tourism.opendatahub.bz.it and click on Log in (top right
 corner)
 
 .. figure:: /images/events/login.png
-   :width: 90%
-
+   :scale: 33%
+   :align: center
+
    Upper section of the tourism portal.
 
 Provide your credentials, then you will be redirected to your
@@ -41,8 +42,9 @@ Events EURAC NOI` (see :numref:`newevent`).
 .. _newevent:
 
 .. figure:: /images/events/newevent.png
-   :scale: 70%
-
+   :scale: 33%
+   :align: center
+
    Menu item to create a new event
 
 You will now see a list of events that will take place at Bolzano's
@@ -52,8 +54,9 @@ are shown. If the event is marked as :strong:`Active`, it is displayed
 on the official NOI web page at https://today.noi.bz.it/.
 
 .. figure:: /images/events/eventlist.png
-   :width: 90%
-
+   :scale: 33%
+   :align: center
+
    List of events.
 
 In order to add a new event, click on the :greenbtn:`New` button to
@@ -63,8 +66,9 @@ In the dialog that opens, fill in all the fields you deem necessary,
 but at least the title, organiser, location, and time.
 
 .. figure:: /images/events/createevent.png
-   :width: 90%
-
+   :scale: 33%
+   :align: center
+
    An example event with a few details provided.
 
 Remember to tick the `Active` and `noi.bz.it Active` checkboxes: The
@@ -100,8 +104,9 @@ list.
 .. _listedevent:
 
 .. figure:: /images/events/listedevent.png
-   :width: 90%
-
+   :scale: 33%
+   :align: center
+
    List with the new event.
 
 Note that the title of the event is shown in the list in the language
@@ -118,9 +123,10 @@ changed as well. These changes are shown in picture
 .. _modifyevent:
 
 .. figure:: /images/events/modifyevent.png
-   :width: 90%
-
-   Changing  event's details.
+   :scale: 33%
+   :align: center
+
+   Changing event's details.
 
 Click on :blackbtn:`Save` to save the modified event.