Improve README file and templates

README.md

@@ -1,10 +1,10 @@
-# Onfido OpenAPI specification
+# Onfido OpenAPI Specification
 
 ## Introduction
 
 This specification supports the latest version of the Onfido API (v3.6).
 
-It can also be used for generating client libraries to allow backend services to interact with the Onfido API. A [Postman collection](#api-documentation) is provided as well for user's convenience.
+It can also be used for generating client libraries to allow backend services to interact with the Onfido API. Additionally, a [Postman collection](#api-documentation) is provided for user convenience.
 
 ## Client libraries
 
@@ -22,13 +22,13 @@ The libraries below are generated and maintained by Onfido:
 - [onfido-python](https://github.com/onfido/onfido-python)
 - [onfido-ruby](https://github.com/onfido/onfido-ruby)
 
-Libraries come with Webhook Events validation and the possibility to easily choose a region to target.
+Libraries come with Webhook Events validation. They also provide the possibility to easily choose a region to target.
 
 Please find more information regarding how to use each library within their own README.md file.
 
 ### How to build client libraries yourself
 
-Please find in [OpenAPI Generator documentation](https://openapi-generator.tech) how to build client libraries and all the supported programming languages to build client libraries.
+Refer to the [OpenAPI Generator documentation](https://openapi-generator.tech) for the list of supported programming languages and instructions on building client libraries.
 
 The file [openapi.yaml](openapi.yaml) should be provided to the generator.
 
@@ -64,7 +64,7 @@ A few exceptions come from a global exclusion list (defined as part of the rsync
 
 For each generator, additional exclusions are defined into specific [exclusions.txt files](https://github.com/search?q=repo%3Aonfido%2Fonfido-openapi-spec+path%3A**%2Fexclusions.txt&type=code) stored in each generator's folder.
 
-Code is automatically generated into the [generated/artifacts](generated/artifacts) subfolders and pushed to each client library repository via automatically generated PRs. Every path matching the exclusion lists defined above is neither copied from artifact folder nor removed from the target client library repository: that’s the way for avoid pushing some contents to client libraries but also avoiding some files (tests and git files) from being removed or overridden.
+Code is automatically generated into the [generated/artifacts](generated/artifacts) subfolders and pushed to each client library repository via automatically generated PRs. Every path matching the exclusion lists defined above is neither copied from the artifact folder nor removed from the target client library repository. That’s the way to avoid pushing some contents to client libraries but also avoid some files (tests and git files) from being removed or overridden.
 
 A few files are automatically generated and committed in the [generated/artifacts](generated/artifacts) folder at PR merge time.
 
@@ -106,7 +106,7 @@ This happens when templates we're overriding have been updated. The script autom
 3. Add all changes from the new version except the ones noted by mustache comments (i.e. `{{! }}`)
 4. Commit changes to both templates and SHA256SUM files
 
-The changes to README.md should be carefully reviewed by comparing `generated/templates/**/README.mustache` files created with different OpenAPI generator versions.
+The changes to `README.md` should be carefully reviewed by comparing `generated/templates/**/README.mustache` files created with different OpenAPI generator versions.
 
 ## Contributing
 

generators/common/templates/README_footer.mustache

@@ -1,6 +1,6 @@
 ## Contributing
 
-This library is automatically generated using [OpenAPI Generator](https://openapi-generator.tech) (version: {{generatorVersion}}); therefore all the contributions, except tests files, should target [Onfido OpenAPI specification repository](https://github.com/onfido/onfido-openapi-spec/tree/master) instead of this repository.
+This library is automatically generated using [OpenAPI Generator](https://openapi-generator.tech) (version: `{{generatorVersion}}`); therefore all contributions, except test files, should target the [Onfido OpenAPI specification repository](https://github.com/onfido/onfido-openapi-spec/tree/master) instead of this repository. Please follow the contribution guidelines provided in the OpenAPI specification repository.
 
 For contributions to the tests instead, please follow the steps below:
 
@@ -13,7 +13,9 @@ For contributions to the tests instead, please follow the steps below:
 
 ## Versioning policy
 
-[Semantic Versioning](https://semver.org) policy is used for library versioning, following guidelines and limitations below:
+Versioning helps manage changes and ensures compatibility across different versions of the library.
+
+[Semantic Versioning](https://semver.org) policy is used for library versioning, following the guidelines and limitations below:
 
 - MAJOR versions (x.0.0) might:
   - target a new API version

generators/python/urllib3/templates/README.mustache

@@ -4,10 +4,10 @@ The official Python library for integrating with the Onfido API.
 
 Documentation can be found at <{{ documentationUrl }}>.
 
-This version uses Onfido API {{ apiVersion }}. Refer to our [API versioning guide](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) for details of which client library versions use which versions of the API.
+This version uses Onfido API `{{ apiVersion }}`. Refer to our [API versioning guide](https://developers.onfido.com/guide/api-versioning-policy#client-libraries) for details of which client library versions use which versions of the API.
 
-[![PyPI version](https://badge.fury.io/py/{{{distributionPackageName}}}.svg)](https://badge.fury.io/py/{{{distributionPackageName}}})
-![Build Status](https://github.com/{{{gitUserId}}}/{{{gitRepoId}}}/actions/workflows/python.yml/badge.svg)
+[![PyPI version](https://badge.fury.io/py/onfido-python.svg)](https://badge.fury.io/py/onfido-python)
+[![Build Status](https://github.com/onfido/onfido-python/actions/workflows/python.yml/badge.svg)](https://github.com/onfido/onfido-python/actions/workflows/python.yml)
 
 ## Installation & Usage
 
@@ -19,13 +19,13 @@ Python {{{generatorLanguageVersion}}}
 
 #### Pip
 
-If the python package is hosted on a repository, you can install directly using:
+Install the package using pip:
 
 ```sh
 pip install {{{distributionPackageName}}}
 ```
 
-Then import the package:
+Import the package:
 
 ```python
 import {{{packageName}}}
@@ -43,9 +43,13 @@ Then import the package:
 import {{{packageName}}}
 ```
 
-### Tests
+## Running Tests
+
+To run the tests with `pytest` and disable output capture, use the following command:
 
-Execute `pytest` to run the tests.
+```sh
+poetry run pytest --show-capture=no
+```
 
 ## Getting Started
 
@@ -68,7 +72,7 @@ with {{{packageName}}}.ApiClient(configuration) as api_client:
   ...
 ```
 
-NB: by default, timeout values are set to 30 seconds.
+Note: by default, timeout values are set to 30 seconds.
 
 ### Making a call to the API
 
@@ -97,7 +101,7 @@ Specific exception types are defined into [exceptions.py](onfido/exceptions.py).
 
 ### Webhook event verification
 
-Webhook events payload needs to be verified before it can be accessed. Library allows to easily decode the payload and verify its signature before returning it as an object for user convenience:
+Webhook event payloads need to be verified before they can be accessed. The library allows you to easily decode the payload and verify its signature before returning it as an object for your convenience:
 
 ```python
   try:
@@ -115,6 +119,6 @@ Webhook events payload needs to be verified before it can be accessed. Library a
 
 #### Do not use additional properties
 
-Retain from using `additional_properties` dictionary to access not defined properties to avoid breaking changes when these fields will appear.
+Avoid using the `additional_properties` dictionary to access undefined properties, as this may cause breaking changes when these fields are added in the future.
 
 {{>README_footer}}