Align readme and doc entry pages as much as possible

Author: iMichka

README.rst

@@ -14,20 +14,43 @@ pygccxml
     :target: http://pygccxml.readthedocs.io/en/develop/?badge=develop
     :alt: Documentation status
 
-pygccxml is a specialized XML reader that reads the output from CastXML or GCCXML. It provides a simple framework to navigate C++ declarations, using Python classes.
+pygccxml is a specialized XML reader that reads the output from CastXML.
+It provides a simple framework to navigate C++ declarations, using Python classes.
 
-Install
--------
+Using pygccxml you can:
+
+* Parse C++ source code
+* Create a code generator
+* Generate UML diagrams
+* Build code analyzers
+* ...
+
+Installation
+------------
 
 Install instructions can be found `here <http://pygccxml.readthedocs.io/en/master/install.html>`_.
 
+Compatibility
+-------------
+
+pygccxml is compatible with Python 2.7, 3.3, 3.4, 3.5, pypy and pypy3.
+
 Documentation and examples
 --------------------------
 
 The documentation can be found `here <http://pygccxml.readthedocs.io>`_, examples can be found `here <http://pygccxml.readthedocs.io/en/master/examples.html>`_.
 
+If you want to know more about the API provided by pygccxml, read the
+ `query interface <http://pygccxml.readthedocs.io/en/develop/query_interface.html>`_ document or the
+ `API documentation <http://pygccxml.readthedocs.io/en/develop/apidocs/modules.html>`_.
+
 A `FAQ <http://pygccxml.readthedocs.io/en/master/faq.html>`_ is also available and may answer some of your questions.
 
+License
+-------
+
+`Boost Software License <http://boost.org/more/license_info.html>`_
+
 Contact us
 ----------
 
@@ -45,9 +68,8 @@ The develop branch contains the latest improvements but can be unstable. Pull Re
 Testing and code coverage
 -------------------------
 
-pygccxml has more than 250 unit tests. They are run after each code commit to ensure
-that the code stays functional and stable. You can find the Mac and Linux builds `here <https://travis-ci.org/gccxml/pygccxml/builds>`_ and
-the Windows builds `here <https://ci.appveyor.com/project/iMichka/pygccxml>`_.
+You can find the Mac and Linux builds `here <https://travis-ci.org/gccxml/pygccxml/builds>`_.
+The Windows builds are located `here <https://ci.appveyor.com/project/iMichka/pygccxml>`_.
 
 Running the test suite is done with:
 

docs/index.rst

@@ -1,50 +1,73 @@
 pygccxml
 ========
 
-The purpose of `pygccxml` is to read a generated xml file and provide a simple
-framework to navigate C++ declarations, using Python classes.
+pygccxml is a specialized XML reader that reads the output from CastXML.
+It provides a simple framework to navigate C++ declarations, using Python classes.
 
-Using `pygccxml` you can:
+Using pygccxml you can:
 
 * Parse C++ source code
-* Create a powerful code generator
+* Create a code generator
 * Generate UML diagrams
 * Build code analyzers
 * ...
 
 Installation
-============
+------------
 
 Installation instructions can be found here: :doc:`Installation <install>`
 
-Examples
-========
+Compatibility
+-------------
+
+pygccxml is compatible with Python 2.7, 3.3, 3.4, 3.5, pypy and pypy3.
 
-The :doc:`examples <examples>` are a good way to learn how to use `pygccxml`.
+Documentation and examples
+--------------------------
 
-`pygccxml` provides a powerful API. If you want to know more about the provided API
+The :doc:`examples <examples>` are a good way to learn how to use pygccxml.
+
+If you want to know more about the API provided by pygccxml,
 read the :doc:`query interface <query_interface>` document or the
 :doc:`API documentation <apidocs/modules>`.
 
-Contributing
-============
-
+A `FAQ <faq>`_ is also available and may answer some of your questions.
 
 License
-=======
+-------
+
+`Boost Software License <http://boost.org/more/license_info.html>`__
+
+Contact us
+----------
+
+You can contact us through the `CastXML mailing list <http://public.kitware.com/mailman/listinfo/castxml/>`__.
+
+For issues with pygccxml you can open an issue `here <https://github.com/gccxml/pygccxml/issues/>`__.
 
-`Boost Software License`_.
+Branches
+--------
+
+The stable version can be found on the master branch.
+
+The develop branch contains the latest improvements but can be unstable. Pull Requests should be done on the develop branch.
 
 Test environment
-================
+----------------
+
+You can find the Mac and Linux builds `here <https://travis-ci.org/gccxml/pygccxml/builds>`__.
+The Windows builds are located `here <https://ci.appveyor.com/project/iMichka/pygccxml>`__.
+
+Running the test suite is done with:
 
-`pygccxml` comes with comprehensive unit tests. They are executed on different operating systems,
-and with different versions of compilers. See the `Travis`_ builds for more details.
-`pygccxml` is tested under python 2.6, 2.7, 3.2, 3.3, 3.4, 3.5. All in all, `pygccxml` has more than 230 tests.
+.. code-block:: python
 
+  python3 -m unittests.test_all
+
+Code coverage is also available. It is automatically updated after each commit and can be found `here <https://coveralls.io/r/gccxml/pygccxml>`__.
 
 Documentation contents
-======================
+----------------------
 
 .. toctree::
    :maxdepth: 1
@@ -62,13 +85,8 @@ Documentation contents
    history
    upgrade_issues
 
-.. _`Boost Software License`: http://boost.org/more/license_info.html
-.. _`Travis`: https://travis-ci.org/gccxml/pygccxml/builds
-.. _`boost::type_traits` : http://www.boost.org/libs/type_traits/index.html
-
-
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`