Merge pull request #202 from noi-techpark/issue-194-add-changelog

Issue 194 add changelog

source/appendices.rst

@@ -10,4 +10,4 @@ The following is the list of appendices.
 
    glossary
    licenses
-
+   changelog

source/changelog.rst

@@ -0,0 +1,37 @@
+Changelog
+=========
+
+.. versionadded:: 2021.03 Add extension to provide structured
+   Changelogs
+
+This section contains the Changelog of the |odh| project's
+documentation.
+
+* Previous to June 2020, we maintained no changelog.
+* The list of changes made from June, 2020 to February, 2021 can be
+  :download:`downloaded <changelog.txt>` as a text file.
+
+* Since March 2021 we adopted a more structured approach: This section
+  indeed will contain an entry for each change made to the
+  documentation.
+
+.. note:: We do not schedule regular releases of the documentation, we
+	rather publish new versions `"When they are ready"`, therefore each
+	`version` is identified by a string :strong:`YYYY.MM`, in which
+	`YYYY` is the year and `MM` the month of the release.
+
+.. changelog::
+    :version: 2021.03
+    :released: 31 March 2021
+
+    .. change::
+       :tags: Improvement
+       :tickets: 194
+
+       Add :strong:`changelog` extension.
+
+    .. change::
+       :tags: Bugfix
+       :tickets: 199
+
+       Fix layout of datasets in :ref:`Other Domains <other-domains-datasets>`.

source/changelog.txt

@@ -0,0 +1,55 @@
+*** ['Changes in Version 2020.06 — OpenDataHub Docs Repo']
+
++ Changed :: Direct link to the browsable version of the datasets.
+
+*** ['Changes in Version 2020.09 — OpenDataHub Docs Repo']
+
++ New :: New domain category Other, which includes dataset that do not belong to existing domains
++ New :: New description of domains, new diagrams that show the datasets encompassed in each domain
++ New :: Added article, common, venue and eventshort datasets
++ Changed :: Updated the list of data providers
++ Changed :: Improved description of datasets in the mobility domain,
+             including external links, use cases, and Data Providers. 
++ Changed :: added dropdowns to the list of datasets to improve usability
++ Changed :: Improved description of datasets in the mobility/mobility domain, including new information
++ Changed :: Removed datasets not offered directly from Open Data Hub (siag.museum and siag.weather)
++ Changed :: Renamed weather-siag dataset to weather-forecast
++ Changed :: Ordered datasets in alphabetical order
+
+*** ['Changes in Version 2020.10 — OpenDataHub Docs Repo']
+
++ New :: Information about licensing of data contained in the ODH responses
++ New :: Links from the dataset lists to the howto section
++ New :: API URL for all Tourism datasets.
++ New :: edgeTypes method.
++ New :: Rewritten introduction and added description of possible actors involved in the odh and how thei
++ Changed :: Panels layout was replaced with tabs in the Alpha Stage application list.
++ Changed :: Changed identifier of datasets activity, event, gastronomy, package, and POI
++ Changed :: Authentication to internal infrastructure does not require client_secret and credentials anyumore
++ Changed :: Panels layout was replaced by tabs in the howto list.
++ Changed :: New types of representation for API calls
++ Changed :: Rewritten introduction and added description of possible
+		           actors involved in the Open Data Hub and how their possible
+             interactions with the Open Data Hub project.
++ Changed :: Panels layout was modified to fix the wrong visualisation in the Getting Involved section.
++ Deprecated :: Public Transportation dataset
+
+*** ['Changes in Version 2020.11 — OpenDataHub Docs Repo']
+
++ New :: description of logical operators
++ New :: timezone
+
+*** ['Changes in Version 2020.12 — OpenDataHub Docs Repo']
+
++ New :: explanation about string values in WHERE clauses
+
+*** ['Changes in Version 2021.01 — OpenDataHub Docs Repo']
+
++ New :: access to data with SPARQL
++ New :: data access with R.
++ Changed :: Reorganised presentation of the data-access section
+
+*** ['Changes in Version 2021.02 — OpenDataHub Docs Repo']
+
++ New :: odh Virtual Knowledge Graph and description of underlying Knowledge Model
++ New :: Description of the Knowledge Model underlying datasets Accommodation, Gastronomy, and Event datasets

source/conf.py

@@ -30,7 +30,7 @@
     'sphinx.ext.imgconverter',
     'ga', 'hidemail',
     'sphinx_togglebutton', 'sphinx_panels',
-    'sphinx_copybutton'
+    'sphinx_copybutton', 'changelog'
 ]
 
 ### Configuration values for extensions
@@ -41,6 +41,15 @@
 copybutton_prompt_is_regexp = True
 
 
+# section names - we don't need them 
+#changelog_sections = ["Improvements", "Changes", "Bugfix"]
+
+# tags to sort on inside of sections
+changelog_inner_tag_sort = ["Improvement", "Change", "Bugfix"]
+# whether sections should be hidden from tags list
+#changelog_hide_sections_from_tags = False
+changelog_render_ticket = "https://github.com/noi-techpark/odh-docs/issues/%s"
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
@@ -64,7 +73,7 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'2021.01'
+version = u'2021.03'
 # The full version, including alpha/beta/rc tags.
 release = version
 

source/datasets.rst

@@ -3,23 +3,6 @@
 Datasets
 ========
 
-.. versionadded:: 2020.09 New domain category `Other`, which includes
-   dataset that do not belong to existing domains
-
-.. versionadded:: 2020.09 New description of domains, new diagrams
-   that show the datasets encompassed in each domain
-
-.. versionadded:: 2020.10 Information about licensing of data
-   contained in the |ODH| responses
-
-.. versionadded:: 2020.10 Links from the dataset lists to the howto
-   section
-
-.. versionadded:: 2021:01 access to data using R
-
-.. versionchanged:: 2021.01 Reorganised presentation of the
-   :ref:`data-access` section
-
 .. versionadded:: 2021.01 access to data with SPARQL
 
 .. versionadded:: 2021.02 |odh| Virtual Knowledge Graph and
@@ -530,16 +513,6 @@ find information about winter and summer offers from local touristic
 boards, information about weather, hotels and accommodation, Points of
 Interests, and a lot more.
 
-.. versionchanged:: 2020.09 Removed datasets not offered directly from
-   Open Data Hub (siag.museum and siag.weather)
-
-.. versionchanged:: 2020.09 Renamed weather-siag dataset to
-   weather-forecast
-
-.. versionchanged:: 2020.09 Ordered datasets in alphabetical order
-
-.. versionadded:: 2020.09 Added article, common, venue and eventshort datasets
-
 .. versionchanged:: 2020.10 Changed identifier of datasets activity,
    event, gastronomy, package, and POI
 
@@ -669,6 +642,7 @@ The following information is provided for each dataset in the Tourism domain:
 
    .. include:: /datasets/webcam.rst
 
+.. _other-domains-datasets:
 
 Datasets in Other Domains
 -------------------------

source/howto/mobility/getstarted.rst

@@ -2,8 +2,6 @@
 
 How to Access Mobility Data With API v2
 =======================================
-
-.. versionadded:: 2020-April
 
 The new :strong:`API v2` (see :ref:`the description <ninja api>`) for
 the Mobility domain has simplified the access to data; among its
@@ -91,15 +89,9 @@ incrementally refine the data retrieved. They are:
    datasets. to be used in the next methods. See :ref:`the details
    below <representation-types>`. 
 
-   .. versionadded:: 2020-June API method to retrieve the list of
-      dataset's entry point.
-
 #. :literal:`/v2/{representation}/` shows all the StationTypes
    available, that is, all the sources that provided data to the Open
    Data Hub.
-
-   .. versionadded:: 2020-June API method to retrieve the list of all
-      stationTypes available.
 
 #. :literal:`/v2/{representation}/{stationTypes}` returns data about
    the stations themselves, including metadata associated with each, and
@@ -114,15 +106,12 @@ incrementally refine the data retrieved. They are:
 #. :literal:`/v2/{representation}/{stationTypes}/{dataTypes}`.  In
    addition to the data of the previous call, it contains the data
    types defined in the dataset.
+
 #. :literal:`/v2/{representation}/{stationTypes}/{dataTypes}/latest`. In
    addition to all the data retrieved by the previous call, this call
    retrieves also the most recent measurement. This method is
    especially suited for real time retrieval of data.
-
-
-   .. versionadded:: 2020-June API method to retrieve the list of
-      latest/real time measurements
-
+
 #. :literal:`/v2/{representation}/{stationTypes}/{dataTypes}/{from}/{to}`.
    All the data retrieved by method #3, but limited to a
    given historical interval (:literal:`from` ... :literal:`to`).
@@ -460,8 +449,6 @@ keys described in the previous two section are valid and can be used.
 
 Advanced Data Processing
 ------------------------
-
-.. versionchanged:: 2020-May keyword alias was replaced by :strong:`target`.
 
 Before introducing advanced data processing techniques, we recall that
 queries against the Open Data Hub's datasets always return a
@@ -645,8 +632,6 @@ The above example will be translated into Postgres as follows:
 Additional Parameters
 ~~~~~~~~~~~~~~~~~~~~~
 
-.. versionadded:: 2020-May `shownull` and `distinct`.
-
 .. versionadded:: 2020.11 `timezone`
 
 There are a couple of other parameter that can be given to the API