Revamp README.md with structured information

[edoaltamura]

What should we add?

Restructure the Readme file with a more structured introduction. Proposal:

What is <>?

How do I install <>?

You can install <> from the Python Package Index (PyPI) by running:

pip install <>

It is also possible to install <> using conda:

conda install -c conda-forge <>

Our Get Started guide contains full installation instructions and includes how to set up Python virtual environments.

Installation from source

To access the latest version before its official release, install it from the main branch.

pip install git+https://github.com/<>@main

What are the main features of <>?

How do I use <>?

Why does <> exist?

The maintainers

• STFC Hartree
• IBM Quantum
• Open source contributors

Can I contribute?

We welcome all kinds of contributions. Check out our guide to contributing.

Where can I learn more?

There is a growing community. We encourage you to ask and answer technical questions on Slack.

How can I cite <>?

If you're an academic, <> can also help you, for example, as a tool to do [...]. Use the "Cite this repository" button on our repository to generate a citation from the CITATION.cff file.

Python version support policy

• The core <> Framework supports all Python versions that are actively maintained by the CPython core team. When a Python version reaches end of life, support for that version is dropped. This is not considered a breaking change.

[woodsp-ibm]

As a general comment you can see the existing sections followed the same pattern as Qiskit (same for the other applications and algorithms). In the past it was helpful since if needed/wanted any changes were similar across the set of repos. With the repos now under more individual maintainership having something different seems fine. As to sections like where to learn more and how to use - I would have thought tutorials and how to docs. Qiskit Nature started to add them in trying to do the docs more in the diataxis form, so the how to section would point to howtos when they existed. As to the Python support policy what versions have more come down to Qsikit since thats a key dependent. Once a version hits its support EOL then it does get dropped, it may take a while though for a new version to get supported based on how quickly all the key dependents support that new version.

Another couple of notes. One is that the sample code in the readme is extracted in one of the unit tests and run to make sure it stayed working. The other is that the content of the readme is embedded in the package that is published out on pypi (with the exception of some status items) so it shows up there too.

[edoaltamura]

We could also add the following shields:

And finally the badge for https://www.bestpractices.dev/en/criteria/0

[edoaltamura]

Issue #807 can be thought of as part of this README update.

[edoaltamura]

Now that some of the README.md is updated, the outstanding points to improve are:

• Restructured outlook of the main features
• Restructured quickstart example
• Instructions to install from source
• A list of Awesome Qiskit Machine Learning projects anywhere else on GitHub which demonstrate neat functionalities perhaps implemented in research papers.