DOC: reshape contents and improve docs

The doc frontpage is more lean and some minor adjustements in the text.

docs/conf.py

@@ -33,7 +33,7 @@
 apidoc_excluded_paths = ["tests"]
 apidoc_separate_modules = True
 apidoc_module_first = True
-apidoc_extra_args = ["-H", "XTGeo API description"]
+apidoc_extra_args = ["-H", "XTGeo API reference"]
 
 autoclass_content = "both"
 
@@ -48,7 +48,7 @@
 # General information about the project.
 project = "xtgeo"
 current_year = date.today().year
-copyright = "Equinor 2019 - " + str(current_year)
+copyright = "Equinor 2019 - " + str(current_year) + f" (XTGeo release {release})"
 
 
 # Sort members by input order in classes

docs/index.rst

@@ -1,8 +1,13 @@
 Welcome to XTGeo's documentation!
 ===========================================
 
-Contents:
+.. figure:: images/xtgeo-logo3.svg
+     :alt: Logo
+     :width: 300
+     :align: center
 
+Contents
+--------
 .. toctree::
    :maxdepth: 1
 
@@ -11,13 +16,23 @@ Contents:
    installation
    contributing
    datamodels
-   apiref/modules
    usage
    usextgeoroxar
    authors
 
+API reference
+-------------
+The API documentation is autogenerated from the source code. It provides
+an up-to-date documentation of all public classes and methods.
+
+.. toctree::
+   :maxdepth: 1
+
+   apiref/modules
+
+
 Indices and tables
-==================
+------------------
 
 * :ref:`genindex`
 * :ref:`modindex`

docs/usage.rst

@@ -1,14 +1,15 @@
 .. highlight:: python
 
-========
-Examples
-========
+==============================
+Examples in standalone scripts
+==============================
 
 .. comments
    These examples are ran in Jupyter notebook...
 
 XTGeo is Python library to work with surfaces, grids, cubes, wells, etc,
-possibly in combinations.
+possibly in combinations. It is easy to make small user scripts that runs from
+the command line in Linux, Mac and Windows.
 
 ------------------
 Surface operations

docs/usextgeoroxar.rst

@@ -1,11 +1,21 @@
 .. highlight:: python
 
-===============================
-Examples on use of XTGeo in RMS
-===============================
+==========================
+Examples on use inside RMS
+==========================
+
+.. _RMS: https://www.emerson.com/no-no/automation/operations-business-management/reservoir-management-software
+
+RMS_ is a licensed proprietary modeling software developed by Emerson.
+From version 10 it has its own python engine integrated, and XTGeo is designed
+to work inside this environment. The integration will be continuously improved.
+
+Hence XTGeo can read most datatypes that are exposed in RMS' API (called ROXAPI),
+and then all native methods in XTGeo can be applied on those data. For example,
+if you want to write a surface from RMS to a format that ROXAPI does not
+support, but XTGeo supports, then it is quite easy. XTGeo can also read data from
+external files and store the data in the RMS data tree.
 
-XTGeo can be incorporated within the RMS user interface and share
-data with RMS. The integration will be continuosly improved.
 Note that all these script examples are assumed to be ran inside
 a python job within RMS.