first proposal to improve the README (#133)

* Improved the README file to give required informations to understand what is AnyBlok and to start working with AnyBlok or even working on AnyBlok. * Updated FRONT.rst accordingly to the README so informations are the same between README and documentation * Removed FRONT.rst content from long description in setup.py to avoid duplicated content in Pypi
AnyBlok · Nov 22, 2019 · 5cd35b6 · 5cd35b6
1 parent e73caa1
commit 5cd35b6
Show file tree

Hide file tree

Showing 3 changed files with 137 additions and 48 deletions.
diff --git a/README.rst b/README.rst
@@ -2,14 +2,12 @@
 ..
 ..    Copyright (C) 2014 Jean-Sebastien SUZANNE <jssuzanne@anybox.fr>
 ..    Copyright (C) 2019 Jean-Sebastien SUZANNE <js.suzanne@gmail.com>
+..    Copyright (C) 2019 Hugo QUEZADA <gohu@hq.netlib.re>
 ..
 .. This Source Code Form is subject to the terms of the Mozilla Public License,
 .. v. 2.0. If a copy of the MPL was not distributed with this file,You can
 .. obtain one at http://mozilla.org/MPL/2.0/.
 
-.. image:: https://img.shields.io/pypi/pyversions/anyblok.svg?longCache=True
-    :alt: Python versions
-
 .. image:: https://img.shields.io/pypi/v/AnyBlok.svg
    :target: https://pypi.python.org/pypi/AnyBlok/
    :alt: Version status
@@ -21,16 +19,22 @@
 .. image:: https://coveralls.io/repos/github/AnyBlok/AnyBlok/badge.svg?branch=master
     :target: https://coveralls.io/github/AnyBlok/AnyBlok?branch=master
     :alt: Coverage
-   
+
 .. image:: https://readthedocs.org/projects/anyblok/badge/?version=latest
     :alt: Documentation Status
     :scale: 100%
     :target: https://doc.anyblok.org/en/latest/?badge=latest
-   
+
 .. image:: https://badges.gitter.im/AnyBlok/community.svg
     :alt: gitter
     :target: https://gitter.im/AnyBlok/community?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge
 
+.. image:: https://img.shields.io/pypi/pyversions/anyblok.svg?longCache=True
+    :alt: Python versions
+
+.. image:: https://img.shields.io/static/v1?label=Compatible%20with&message=PostgreSQL%20|%20MySQL%20|%20Microsoft%20SQL%20Server&color=informational
+    :alt: Dialects compatibility
+
 AnyBlok
 =======
 
@@ -39,4 +43,94 @@ applications on top of SQLAlchemy.
 
 AnyBlok is released under the terms of the `Mozilla Public License`.
 
-See the `latest documentation <http://doc.anyblok.org/>`_
+AnyBlok is hosted on `github <https://github.com>`_ - the main project
+page is at https://github.com/anyblok/anyblok or
+http://code.anyblok.org. source code is tracked here
+using `git <https://git-scm.com>`_.
+
+Releases and project status are available on Pypi at
+https://pypi.python.org/pypi/anyblok.
+
+The most recent published version of the documentation should be at
+https://doc.anyblok.org.
+
+There is a tutorial to teach you how to develop applications with AnyBlok at
+https://anyblok.gitbooks.io/anyblok-book/content/en/
+
+Project Status
+--------------
+
+AnyBlok is expected to be stable.
+Some early partners are using it on production and are involved in
+the project development.
+We are aiming to make a stable release as soon as possible.
+
+Users should take care to report bugs and missing features on an as-needed
+basis.
+
+It should be expected that the development version may be required
+for proper implementation of recently repaired issues in between releases;
+the latest master is always available at https://github.com/AnyBlok/AnyBlok/archive/master.zip.
+
+Installation
+------------
+
+Install released versions of AnyBlok from the Python package index with
+`pip <http://pypi.python.org/pypi/pip>`_ or a similar tool::
+
+    pip install anyblok
+
+Installation via source distribution is via the ``setup.py`` script::
+
+    python setup.py install
+
+Installation will add the ``anyblok`` commands to the environment.
+
+Running Tests
+-------------
+
+To run framework tests with ``pytest``::
+
+    pip install pytest
+    ANYBLOK_DATABASE_DRIVER=postgresql ANYBLOK_DATABASE_NAME=test_anyblok py.test anyblok/tests
+
+To run tests of all installed bloks::
+
+    anyblok_createdb --db-name test_anyblok --db-driver-name postgresql --install-all-bloks
+    ANYBLOK_DATABASE_DRIVER=postgresql ANYBLOK_DATABASE_NAME=test_anyblok py.test anyblok/bloks
+
+AnyBlok is tested continuously using `Travis CI
+<https://travis-ci.org/AnyBlok/AnyBlok>`_
+
+Contributing (hackers needed!)
+------------------------------
+
+AnyBlok is ready for production usage even though it can be
+improved and enriched.
+Feel free to fork, talk with core dev, and spread the word !
+
+Author
+------
+
+Jean-Sébastien Suzanne
+
+Contributors
+------------
+
+* Jean-Sébastien Suzanne
+* Georges Racinet
+* Pierre Verkest
+* Franck Bret
+* Denis Viviès
+* Alexis Tourneux
+* Hugo Quezada
+* Simon André
+* Florent Jouatte
+* Christophe Combelles
+* Sébastien Chazallet
+
+Bugs
+----
+
+Bugs and features enhancements to AnyBlok should be reported on the `Issue
+tracker <http://issue.anyblok.org>`_.
diff --git a/doc/FRONT.rst b/doc/FRONT.rst
@@ -2,6 +2,7 @@
 ..
 ..    Copyright (C) 2015 Jean-Sebastien SUZANNE <jssuzanne@anybox.fr>
 ..    Copyright (C) 2016 Jean-Sebastien SUZANNE <jssuzanne@anybox.fr>
+..    Copyright (C) 2019 Hugo QUEZADA <gohu@hq.netlib.re>
 ..
 .. This Source Code Form is subject to the terms of the Mozilla Public License,
 .. v. 2.0. If a copy of the MPL was not distributed with this file,You can
@@ -22,23 +23,37 @@ Information about the AnyBlok project.
 Project Homepage
 ----------------
 
-AnyBlok is hosted on `github <http://github.com>`_ - the main project
+AnyBlok is a Python framework allowing to create highly dynamic and modular
-page is at http://github.com/AnyBlok/AnyBlok or 
+applications on top of SQLAlchemy.
-http://code.anyblok.org. Source code is tracked here
-using `GIT <https://git-scm.com>`_.
 
-Releases and project status are available on Pypi at 
+AnyBlok is released under the terms of the `Mozilla Public License`.
-http://pypi.python.org/pypi/anyblok.
 
-The most recent published version of this documentation should be at
+AnyBlok is hosted on `github <https://github.com>`_ - the main project
-http://doc.anyblok.org.
+page is at https://github.com/anyblok/anyblok or
+http://code.anyblok.org. source code is tracked here
+using `git <https://git-scm.com>`_.
+
+Releases and project status are available on Pypi at
+https://pypi.python.org/pypi/anyblok.
+
+The most recent published version of the documentation should be at
+https://doc.anyblok.org.
+
+There is a tutorial to teach you how to develop applications with AnyBlok at
+https://anyblok.gitbooks.io/anyblok-book/content/en/
 
 Project Status
 --------------
 
-AnyBlok is currently in alpha status and is expected to be fairly
+AnyBlok is expected to be stable.
-stable.   Users should take care to report bugs and missing features on an as-needed
+Some early partners are using it on production and are involved in
-basis.  It should be expected that the development version may be required
+the project development.
+We are aiming to make a stable release as soon as possible.
+
+Users should take care to report bugs and missing features on an as-needed
+basis.
+
+It should be expected that the development version may be required
 for proper implementation of recently repaired issues in between releases;
 the latest master is always available at https://github.com/AnyBlok/AnyBlok/archive/master.zip.
 
@@ -56,7 +71,7 @@ Installation via source distribution is via the ``setup.py`` script::
 
 Installation will add the ``anyblok`` commands to the environment.
 
-.. note:: AnyBlok use Python version >= 3.5
+.. note:: AnyBlok use Python version >= 3.6
 
 Running Tests
 -------------
@@ -78,24 +93,12 @@ To run tests of all installed bloks::
 AnyBlok is tested continuously using `Travis CI
 <https://travis-ci.org/AnyBlok/AnyBlok>`_
 
-Dependencies
-------------
-
-AnyBlok works with **Python 3.5** and later. The install process will 
-ensure that `SQLAlchemy <http://www.sqlalchemy.org>`_, 
-`Alembic <http://alembic.readthedocs.org/>`_,
-`SQLAlchemy-Utils <http://sqlalchemy-utils.readthedocs.org/>`_ are installed, 
-in addition to other dependencies.
-
-AnyBlok works with SQLAlchemy from version **1.3** and newer,
-Alembic from version **0.8.4** and SQLAlchemy-Utils from version **0.31.4**.
-The latest version of them is strongly recommended.
-
-
 Contributing (hackers needed!)
 ------------------------------
 
-Anyblok is at a very early stage, feel free to fork, talk with core dev, and spread the word!
+AnyBlok is ready for production usage even though it can be
+improved and enriched.
+Feel free to fork, talk with core dev, and spread the word !
 
 Author
 ------
@@ -105,20 +108,17 @@ Jean-Sébastien Suzanne
 Contributors
 ------------
 
-`Anybox <http://anybox.fr>`_ team:
+* Jean-Sébastien Suzanne
-
 * Georges Racinet
 * Pierre Verkest
-* Jean-Sébastien Suzanne
+* Franck Bret
+* Denis Viviès
+* Alexis Tourneux
+* Hugo Quezada
 * Simon André
 * Florent Jouatte
 * Christophe Combelles
-
-other:
-
 * Sébastien Chazallet
-* Franck Bret
-* Denis Viviès
 
 Bugs
 ----

diff --git a/setup.py b/setup.py
@@ -8,6 +8,7 @@
 #    Copyright (C) 2018 Jean-Sebastien SUZANNE <jssuzanne@anybox.fr>
 #    Copyright (C) 2019 Jean-Sebastien SUZANNE <jssuzanne@anybox.fr>
 #    Copyright (C) 2019 Jean-Sebastien SUZANNE <js.suzanne@gmail.com>
+#    Copyright (C) 2019 Hugo QUEZADA <gohu@hq.netlib.re>
 #
 # This Source Code Form is subject to the terms of the Mozilla Public License,
 # v. 2.0. If a copy of the MPL was not distributed with this file,You can
@@ -50,12 +51,6 @@
 ) as change:
     CHANGE = change.read()
 
-with open(
-    os.path.join(here, 'doc', 'FRONT.rst'), 'r', encoding='utf-8'
-) as front:
-    FRONT = front.read()
-
-
 extra_dependencies = {
     'pytest': ['pytest', 'pytest-cov'],
     'postgres': ['psycopg2-binary'],
@@ -72,7 +67,7 @@
     author_email="jssuzanne@anybox.fr",
     description="Anyblok is a dynamic injection blok framework",
     license="MPL2",
-    long_description=README + '\n' + FRONT + '\n' + CHANGE,
+    long_description=README + '\n' + CHANGE,
     url="http://docs.anyblok.org/%s" % version,
     packages=find_packages(),
     zip_safe=False,