docs: Update README

Signed-off-by: Ivan Kanakarakis <ivan.kanak@gmail.com>

2 files changed, 104 insertions, 64 deletions

diff --git a/README.md b/README.md
new file mode 100644
index 00000000..90bbc713
--- /dev/null
+++ b/README.md
@@ -0,0 +1,104 @@
+# PySAML2 - SAML2 for Python
+
+[![Version](https://img.shields.io/pypi/v/pysaml2)](https://pypi.org/project/pysaml2/)
+[![Supported Python versions](https://img.shields.io/pypi/pyversions/pysaml2)](https://pypi.org/project/pysaml2/)
+[![Total downloads](https://pepy.tech/badge/pysaml2)](https://pepy.tech/project/pysaml2)
+[![Weekly downloads](https://pepy.tech/badge/pysaml2/week)](https://pepy.tech/project/pysaml2)
+[![License](https://img.shields.io/github/license/IdentityPython/pysaml2)](https://github.com/IdentityPython/pysaml2/blob/master/LICENSE)
+
+PySAML2 is a pure python implementation of SAML Version 2 Standard.
+It contains all necessary pieces for building a SAML2 service provider
+or an identity provider. The distribution contains examples of both.
+Originally written to work in a WSGI environment
+there are extensions that allow you to use it with other frameworks.
+
+**Website**: https://idpy.org/
+
+**Documentation**: https://pysaml2.readthedocs.io/
+
+**Contribution guidelines**: [CONTRIBUTING.md][contributing]
+
+**Security policies**: [SECURITY.md][sec]
+
+**Source code**: https://github.com/IdentityPython/pysaml2/
+
+**Developer guidelines**: [DEVELOPERS.md][dev]
+
+**PyPI project**: https://pypi.org/project/pysaml2/
+
+**License**: [LICENSE][license]
+
+
+## Installation
+
+You can install PySAML2 through pip:
+
+```shell
+pip install pysaml2
+```
+
+### External dependencies
+
+PySAML2 works with the [`xmlsec`][xmlsec] binary.
+This should be readily available in most Linux distributions:
+
+```shell
+$ apt-get install xmlsec1
+$ dnf install xmlsec1-openssl
+$ yum install xmlsec1-openssl
+$ pacman -S xmlsec
+...
+```
+
+and on MacOS through [`homebrew`][brew]
+
+```shell
+$ brew install libxmlsec1
+```
+
+
+## Changelog
+
+See the [CHANGELOG][clog] to learn about the latest developments.
+
+
+## Contributing
+
+We've set up a separate document for our [contribution guidelines][contributing].
+
+
+## Community
+
+[IdentityPython][idpy] is a community around
+a collection of libraries and tools to manage identity related concepts with Python code.
+You can interact with the community though the [mailing list](https://lists.sunet.se/postorius/lists/idpy-discuss.lists.sunet.se/)
+or on the [Slack workspace](https://identity-python.slack.com/) ([invitation](https://join.slack.com/t/identity-python/shared_invite/enQtNzEyNjU1NDI1MjUyLTM2MWI5ZGNhMTk1ZThiOTIxNWY2OTY1ODVmMWNjMzUzMTYxNTY5MzE5N2RlYjExZTIyM2MwYjBjZGE4MGVlMTM)).
+
+
+## Development
+
+We've set up a separate document for [developers][dev].
+
+
+### Releasing
+
+We've set up a separate document for our [release process][rel].
+
+
+### Pre-commit
+
+(TODO)
+
+
+  [idpy]: https://idpy.org/
+  [docs]: https://pysaml2.readthedocs.io/
+  [contributing]: https://github.com/IdentityPython/pysaml2/blob/master/CONTRIBUTING.md
+  [sec]: https://github.com/IdentityPython/pysaml2/blob/master/SECURITY.md
+  [repo]: https://github.com/IdentityPython/pysaml2/
+  [dev]: https://github.com/IdentityPython/pysaml2/blob/master/DEVELOPERS.md
+  [pypi]: https://pypi.org/project/pysaml2/
+  [license]: https://github.com/IdentityPython/pysaml2/blob/master/LICENSE
+  [clog]: https://github.com/IdentityPython/pysaml2/blob/master/CHANGELOG.md
+  [rel]: https://github.com/IdentityPython/pysaml2/blob/master/RELEASE.md
+  [xmlsec]: http://www.aleksey.com/xmlsec/
+  [brew]: https://brew.sh/
diff --git a/README.rst b/README.rst
deleted file mode 100644
index 9cd45e21..00000000
--- a/README.rst
+++ /dev/null
@@ -1,64 +0,0 @@
-*************************
-PySAML2 - SAML2 in Python
-*************************
-
-:Version: see VERSION_
-:Documentation: https://pysaml2.readthedocs.io/
-
-.. image:: https://api.travis-ci.com/IdentityPython/pysaml2.png?branch=master
-    :target: https://travis-ci.com/IdentityPython/pysaml2
-
-.. image:: https://img.shields.io/pypi/pyversions/pysaml2.svg
-    :target: https://pypi.org/project/pysaml2/
-
-.. image:: https://pepy.tech/badge/pysaml2
-    :target: https://pepy.tech/project/pysaml2
-
-.. image:: https://pepy.tech/badge/pysaml2/week
-    :target: https://pepy.tech/project/pysaml2
-
-.. image:: https://img.shields.io/pypi/v/pysaml2.svg
-    :target: https://pypi.org/project/pysaml2/
-
-
-PySAML2 is a pure python implementation of SAML Version 2 Standard. It contains
-all necessary pieces for building a SAML2 service provider or an identity
-provider. The distribution contains examples of both. Originally written to
-work in a WSGI environment there are extensions that allow you to use it with
-other frameworks.
-
-Install
-=======
-You can install with :code:`pip install pysaml2`
-
-Testing
-=======
-
-PySAML2 uses the pytest_ framework for testing. To run the tests on your
-system's version of python:
-
-1. Create and activate a virtualenv_
-2. Inside the virtualenv_, install the dependencies needed for testing
-   :code:`pip install -r tests/test-requirements.txt`
-3. Run the tests :code:`py.test tests`
-
-To run tests in multiple python environments, you can use pyenv_ with tox_.
-
-
-Please contribute!
-==================
-
-To help out, you could:
-
-1. Test and report any bugs or other difficulties.
-2. Implement missing features.
-3. Write more unit tests.
-
-**If you have the time and inclination I'm looking for Collaborators**
-
-
-.. _VERSION: VERSION
-.. _pytest: https://docs.pytest.org/en/latest/
-.. _virtualenv: https://virtualenv.pypa.io/en/stable/
-.. _pyenv: https://github.com/yyuu/pyenv
-.. _tox: https://tox.readthedocs.io/en/latest/