bis-med-it · osirello · Oct 25, 2023 · Oct 24, 2023 · Oct 24, 2023 · Oct 24, 2023
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,41 @@
+## Contributing
+
+We appreciate your interest in contributing. To ensure a smooth and productive collaboration, please read and follow these guidelines.
+
+## Licensing
+
+Please note that the SDMX Dashboard Generator has a [License](LICENCE.pdf). By participating in this project, you acknowledge to comply with it.
+
+## How To Contribute
+
+### Reporting Bugs
+
+You can use GitHub issues to track bugs and requests.
+
+If you spot a problem with the application, [search if an issue already exists](https://github.com/bis-med-it/SDMX-dashboard-generator/issues). If a related issue doesn't exist, you can [open a new issue](https://github.com/bis-med-it/SDMX-dashboard-generator/issues/new) and submit a bug report.
+
+### Suggesting Enhancements
+
+Suggestions for new features and improvements are most welcome. Please [open an issue](https://github.com/bis-med-it/SDMX-dashboard-generator/issues/new) and label it **enhancement**.
+
+- All ideas are welcome!
+- Remember to include sufficient details and context.
+- If you have multiple suggestions please submit them separately so we can track them.
+- Screenshots are always helpful
+
+### Solve An Issue
+
+Scan through our [existing issues](https://github.com/bis-med-it/SDMX-dashboard-generator/issues) to find one that interests you. You can narrow down the search using `labels` as filters.
+If you find an issue to work on, you are welcome to open a PR with a fix.
+
+### Pull Requests
+
+You may open a pull request to:
+
+- Add new features to the application
+- Fix problems that are important to users
+- Maintain the quality of the code
+
+We cordially invite you to use our [Pull Request template](/.github/PULL_REQUEST_TEMPLATE/pull_request_template.md).
+
+Please make sure you follow our style guides integrating [flake8](https://flake8.pycqa.org/en/latest/) and [black](https://black.readthedocs.io/en/stable/index.html). A configuration for the former is already provided, and you can find a [good introduction here](https://medium.com/@huzaifazahoor654/improving-code-quality-with-flake8-and-black-a-guide-for-python-developers-c374168d5884).
diff --git a/README.md b/README.md
@@ -22,11 +22,13 @@
 
 ## About The Project
 
-The objective of hackathon challenge is to develop an open-source responsive web application which effectively reads a specification file and retrieves data from SDMX APIs to create a dynamic dashboard. The web application will provide dashboard designers with a user-friendly interface to create customizable dashboards, effortlessly integrating data from SDMX APIs and offering rich visualization options. The project aims to empower dashboard designers to explore, analyse, and present data from SDMX sources in a visually appealing and intuitive manner.
-
-The SDMX dashboard generator will provide a valuable solution for data analysts, researchers, policymakers, and organizations seeking to harness the power of SDMX data through customizable dashboards. By simplifying the process of integrating SDMX data and specification files, dashboard generator will empower users to gain actionable insights and make informed decisions based on authoritative and up-to-date data. The open-source nature of the dashboard generator will foster collaboration, customization, and community contributions, driving continuous improvement and innovation.
-
-Source: <a href="https://www.sdmx2023.org/hackathon">SDMX 2023 Hackathon</a>
+The SDMX Dashboard Generator (SDMX-DG) is an open-source [Dash](https://dash.plotly.com) application that 
+generates dynamic dashboards by pulling data and metadata from SDMX Rest API. It supports the version 2.1 
+of the standard. It leverages the open-source library SDMXthon to retrieve and parse data and metadata in SDMX. 
+Data and metadata are supported by asynchronous retrieval. A dashboard is composed of several visualizations 
+as defined by the specifications provided in a .yaml file. The specifications are interpreted by a ChartGenerator 
+class containing instructions to define the Plotly charts. It has been developed for the 
+[SDMX Hackathon Global Conference 2023](https://www.sdmx2023.org/hackathon).
 
 ## Documentation
 

diff --git a/docs_src/contributing.md b/docs_src/contributing.md
diff --git a/docs_src/contributing.rst b/docs_src/contributing.rst
@@ -0,0 +1,3 @@
+
+.. include:: ../CONTRIBUTING.md
+    :parser: myst_parser.sphinx_
diff --git a/docs_src/getting_started.md b/docs_src/getting_started.md
@@ -1,4 +1,4 @@
-# Getting started
+# Getting Started
 
 This page contains useful tips to install and run the app.
 Make sure that your environment is correctly set up to execute Python code and that your `pip` and `Python` are up-to-date.
@@ -54,9 +54,9 @@ The app has been successfully tested with Python versions equal or higher to 3.9
 
 5. Open your browser at [http://127.0.0.1:5000](http://127.0.0.1:5000) if you use Flask or [http://127.0.0.1:8050](http://127.0.0.1:8050)
 
-## How to with examples
+## How To With Examples
 
-### Upload the YAML file
+### Upload The Yaml File
 
 The application comes with examples stored in the `/yaml` folder which can be used in two ways:
 
@@ -67,25 +67,25 @@ The application comes with examples stored in the `/yaml` folder which can be us
 
 The application will scan the existing content in the `yaml` subfolder of the project and load the `.yaml` file containing the requested `DashID`. If none is found, the app will raise a `PreventUpdate`.
 
-### Example of YAML file settings
+### Example Of Yaml File Settings
 
 Example of `.yaml` structure (the elements need to follow the indicated order to pass the validation test):
 
 ![Yaml sample](_static/yaml_sample.png "This is a yaml sample.")
 
-- `DashID`: dashboard identifier using any string composed of numbers, letters, and underscores (_), which can be used to compose the URL to display the dashboard. For example, if the base URL of the application is `http://127.0.0.1:5000` and the `DashID` is `eurostat`, the dashboard might be displayed at [http://127.0.0.1:5000/eurostat](http://127.0.0.1:5000/eurostat)
+- `DashID`: dashboard identifier using any string composed of numbers, letters, and underscores, which can be used to compose the URL to display the dashboard. For example, if the base URL of the application is `http://127.0.0.1:5000` and the `DashID` is `eurostat`, the dashboard might be displayed at [http://127.0.0.1:5000/eurostat](http://127.0.0.1:5000/eurostat)
 
 - `Row`: row position of the visual indicated as an integer value 0…3. Up to three charts can share the same row and they are distributed left-right in the order they appear in the specification file. Title, subtitle and footnotes are identified with `Row=0` and `chartType=TITLE` and `chartType=FOOTER` respectively
 
 - `Title`: title description of the chart. If no title is specified, the dashboard shows automatically the name of the requested dataflow, supported by multilingual translation
 
 - `Subtitle`: a string to complement the title description of the chart. If `auto` is provided, the subtitle takes the code name from `legendConcept`. If more than one code name is available, then it will take the first one and append to it `...`. If the subtitle node is empty, no subtitle will be shown
 
-- `Unit`: a string to describe the unit which can be show in the chart if `UnitShow` is set to `Yes`
+- `Unit`: a string to describe the unit which can be shown in the chart if `UnitShow` is set to `Yes`
 
-- `UnitIcon`: a bootstrap icon to be show on top of the KPI. Full list available at: [https://icons.getbootstrap.com/](https://icons.getbootstrap.com)
+- `UnitIcon`: a bootstrap icon to be shown on top of the KPI. Full list available at: [https://icons.getbootstrap.com/](https://icons.getbootstrap.com)
 
-- `Decimals`: the number of decimals to display
+- `Decimals`: the number of decimals
 
 - `chartType`: it can be KPI (i.e. VALUE) or charts (i.e. PIE, LINE and BAR)
 
@@ -103,6 +103,6 @@ Example of `.yaml` structure (the elements need to follow the indicated order to
 
 - `dsdLink`: an URL of an application or file containing related the datastructure data
 
-- `metadataLink`: an URL of an application or file containing reference metadata (e.g. used in the info button). This is field is mandatory if `dsdLink` is provided.
+- `metadataLink`: an URL of an application or file containing reference metadata (e.g. used in the info button). This is field is mandatory if `dsdLink` is provided
 
-- `DATA`: an URL of an application or file containing data
+- `DATA`: an URL of an application or file containing data.
diff --git a/docs_src/index.rst b/docs_src/index.rst
@@ -1,12 +1,13 @@
 Welcome to SDMX Dashboard Generator's documentation!
 ====================================================
 
-SDMX Dashboard generator is an open-source `Dash <https://dash.plotly.com>`_ application that generates dynamic dashboards by 
-pulling data and metadata from SDMX Rest API. It supports the version 2.1 of the standard. It leverages the open-source 
-library `SDMXthon <https://github.com/Meaningful-Data/sdmxthon>`_ to retrieve and parse data and metadata in SDMX. 
-A dashboard is composed of several visualizations as defined by the specifications provided in a `.yaml` file.
-
-This library has been developed for the `SDMX Hackathon Global Conference 2023 <https://www.sdmx2023.org/hackathon>`_.
+The SDMX Dashboard Generator (SDMX-DG) is an open-source [Dash](https://dash.plotly.com) application that 
+generates dynamic dashboards by pulling data and metadata from SDMX Rest API. It supports the version 2.1 
+of the standard. It leverages the open-source library SDMXthon to retrieve and parse data and metadata in SDMX. 
+Data and metadata are supported by asynchronous retrieval. A dashboard is composed of several visualizations 
+as defined by the specifications provided in a .yaml file. The specifications are interpreted by a ChartGenerator 
+class containing instructions to define the Plotly charts. It has been developed for the 
+[SDMX Hackathon Global Conference 2023](https://www.sdmx2023.org/hackathon).
 
 .. image:: _static/light.png
    :width: 1338px

diff --git a/docs_src/troubleshooting.md b/docs_src/troubleshooting.md
@@ -1,9 +1,8 @@
 # Troubleshooting
 
-This page contains information on common issues users encounter when using
-the app and how to avoid/fix them.
+This page contains information on common issues users encounter when using the SDMX-DG application and how to avoid/fix them.
 
-## Use virtual environments
+## Use Virtual Environments
 
 Working in the global Python environment as opposed to project-specific virtual environments may cause a lot of problems.
 We recommend to use [virtual environments](https://docs.python.org/3/library/venv.html>) for running this Python project with the correct package versions.

diff --git a/docs_src/walkthrough.md b/docs_src/walkthrough.md
@@ -1,10 +1,5 @@
 # Walkthrough
 
-## Introduction
-
-SDMX Dashboard Generator is an open-source [Dash](https://dash.plotly.com) application that generates dynamic dashboards by pulling data and metadata from SDMX Rest API.
-It has been developed for the [SDMX Hackathon Global Conference 2023](https://www.sdmx2023.org/hackathon).
-
 ## Main features
 
 <div style="display: flex;">
@@ -148,11 +143,11 @@ It has been developed for the [SDMX Hackathon Global Conference 2023](https://ww
   <img src="_static/dashboard.png" style="max-height: 60px; margin: 10px;"/>
   <details close style="margin: 10px; text-align: left";><summary style="margin: 10px;text-align: center;">The Dash application</summary>
 
-  source code contained in the file `app.py`
+  Source code contained in the file `app.py`
 
-  can run both on locally or shared across the domain
+  Can run both on locally or shared across the domain
 
-  follows the guidelines provided in the [SDMX Hackathon Global Conference 2023 Terms of Reference](https://sdmx.org/wp-content/uploads/SDMX-Hackathon-2023-ToRrev.pdf) (e.g. a maximum of three charts per row is allowed)
+  Follows the guidelines provided in the [SDMX Hackathon Global Conference 2023 Terms of Reference](https://sdmx.org/wp-content/uploads/SDMX-Hackathon-2023-ToRrev.pdf) (e.g. a maximum of three charts per row is allowed)
 
   </details></div>
 
@@ -181,17 +176,17 @@ It has been developed for the [SDMX Hackathon Global Conference 2023](https://ww
 
   Leveraging two classes, `SDMXData` and `SDMXMetadata`, built on top of [SDMXThon](https://github.com/Meaningful-Data/sdmxthon)
 
-  Metadata (e.g. codelist for the legend or multilingual support) retrieval through a metadata url (`dataflow`)
-
-  When supported by SDMX, the metadata is retrieved through DSD url (`datastructure`) to increase the speed performance
+  When supported, metadata retrieval through DSD url (`datastructure`) to increase the speed performance
+  
+  Default retrieval through a metadata url (`dataflow`)
 
   </details></div>
 
   <div style="flex: 1; text-align: center; margin: 10px; background-color: rgba(200, 200, 200, 0.15);">
   <img src="_static/configuration.png" style="max-height: 60px; margin: 10px;"/>
   <details close style="margin: 10px; text-align: left";><summary style="margin: 10px;text-align: center;">The specification file</summary>
 
-The SDMX Dashboard Generator requires a `.yaml` file with the settings for the dashboard. Please see <a href="/getting_started#how-to-with-examples">this example</a> for more details.
+The SDMX Dashboard Generator requires a `.yaml` file with the settings for the dashboard. Please check <a href="/getting_started#how-to-with-examples">this example</a>
 
   </details></div>
 
@@ -209,7 +204,7 @@ The SDMX Dashboard Generator requires a `.yaml` file with the settings for the d
 
   - `chartType:BARS` returns a vertical bars chart including one or multiple series (clustered bars), either time series or cross-sectional
 
-  Each function, with the exception of the one returning the KPI, makes use of `decorator` elements for enriching the chart with style elements (e.g. legendlocation).
+  Each function, with the exception of the one returning the KPI, makes use of `decorator` elements for enriching the chart with style elements.
 
   </details></div>
 

diff --git a/release_notes.md b/release_notes.md
@@ -1,4 +1,4 @@
-# Release notes
+# Release Notes
 
 This page contains an overview of changes for each release.
 Each release is tagged in GitHub and allows for easy download for the different versions.