Cleo doc finaltouches

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
 

docs_src/code_of_conduct.md

@@ -0,0 +1,46 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned to this Code of Conduct, or to ban temporarily or permanently any contributor for other behaviors that they deem inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces when an individual is representing the project or its community. Examples of representing a project or community include using an official project e-mail address, posting via an official social media account, or acting as an appointed representative at an online or offline event. Representation of a project may be further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances. The project team is obligated to maintain confidentiality with regard to the reporter of an incident. Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good faith may face temporary or permanent repercussions as determined by other members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4, available at [https://contributor-covenant.org/version/1/4][version]
+
+[homepage]: https://contributor-covenant.org
+[version]: https://contributor-covenant.org/version/1/4/

docs_src/contributing.md

@@ -1,6 +1,53 @@
-## Contributing
-
-Any contribution is  **greatly appreciated**!
-
-For uniform and clean code, please consider integrating [flake8](https://flake8.pycqa.org/en/latest/) and [black](https://black.readthedocs.io/en/stable/index.html) as part of your workflow.
-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).
+## Contributing
+
+The SDMX Dashboard Generator (SDMX-DG) application has been originally developed by Cristina Stefana Leonte, Pietro Patelli, Stephan Probst and Olivier Sirello (Bank for International Settlements).
+
+We encourage and invite everyone to contribute, as we firmly believe that the strength of our collaborative efforts is amplified by the unique perspectives and talents that each person brings to the table. We foster an inclusive environment where every member is recognized, respected, and empowered to contribute to our collective success.
+
+## How Can I Contribute?
+
+### Reporting Bugs Using Github's [Issues](https://github.com/bis-med-it/SDMX-dashboard-generator/issues)
+
+We use GitHub issues to track bugs.
+
+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.
+
+#### What to Include in a (Good) Bug Report?
+
+- A quick summary and/or background
+- Steps to reproduce
+  - Be specific!
+  - Give sample code if you can.
+- What you expected would happen
+- What actually happens
+- Notes (possibly including why you think this might be happening, or stuff you tried that didn't work)
+
+### 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!
+- Please be courteous and patient.
+- 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
+
+The process described here has several goals:
+
+- Maintain the SDMX-DG's quality
+- Fix problems that are important to users
+- Engage the community in working toward the best possible SDMX-DG
+- Enable a sustainable system for SDMX-DG maintainers to review contributions
+
+Please follow these steps to have your contribution considered by the maintainers:
+
+1. Follow all instructions in [the template](PULL_REQUEST_TEMPLATE.md)
+2. Follow the [styleguides](#styleguides) 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).
+3. After you submit your pull request, verify that all [status checks](https://help.github.com/articles/about-status-checks/) are passing <details><summary>What if the status checks are failing?</summary>If a status check is failing, and you believe that the failure is unrelated to your change, please leave a comment on the pull request explaining why you believe the failure is unrelated. A maintainer will re-run the status check for you. If we conclude that the failure was a false positive, then we will open an issue to track that problem with our status check suite.</details>

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.

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
@@ -35,6 +36,7 @@ This library has been developed for the `SDMX Hackathon Global Conference 2023 <
 
    troubleshooting
    contributing
+   code_of_conduct
 
 Indices and tables
 ==================

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.

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>
 

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.