DOC: Reorganize documentation

CONTRIBUTING.md

@@ -1,59 +1,53 @@
 # Contributing
 
 Contributions are welcome and greatly appreciated! There are several ways to
-contribute to `xtgeo`.
-
+contribute to XTGeo.
 
 ## Types of Contributions
 
-
 ### Report Bugs
 
 Report bugs at
 [https://github.com/equinor/xtgeo/issues](https://github.com/equinor/xtgeo/issues).
 
 If you are reporting a bug, please include:
 
-* Your operating system name and version.
-* Any details about your local setup that might be helpful in troubleshooting.
-* Detailed steps to reproduce the bug.
-
+- Your operating system name and version.
+- Any details about your local setup that might be helpful in troubleshooting.
+- Detailed steps to reproduce the bug.
 
 ### Fix Bugs
 
-Look through the Git issues for bugs. Anything tagged with "bug"
-and "help wanted" is open to whoever wants to implement it.
-
+Look through the GitHub issues for bugs. Anything tagged with "bug", "help
+wanted", or "good first issue" is open to whomever wants to fix it.
 
 ### Implement Features
 
-Look through the Git issues for features. Anything tagged with "enhancement"
-and "help wanted" is open to whoever wants to implement it.
-
+Look through the GitHub issues for features. Anything tagged with
+"enhancement", "help wanted", or "good first issue" is open to whomever wants
+to implement it.
 
 ### Write Documentation
 
-Yes, `xtgeo` could always use more documentation, whether as part of the
-official `xtgeo` docs, in docstrings, or even on the web in blog posts,
+XTGeo could always use improved documentation, whether as part of the
+official XTGeo docs, in docstrings, or even on the web in blog posts,
 articles, and such.
 
-
 ### Submit Feedback
 
 The best way to send feedback is to file an issue at
 [https://github.com/equinor/xtgeo/issues](https://github.com/equinor/xtgeo/issues).
 
 If you are proposing a feature:
 
-* Explain in detail how it would work.
-* Keep the scope as narrow as possible, to make it easier to implement.
-
+- Explain in detail how it would work.
+- Keep the scope as narrow as possible, to make it easier to implement.
 
 ## Get Started!
 
-Ready to contribute? Here's how to set up `xtgeo` for local development.
+Ready to contribute? Here's how to set up XTGeo for local development.
 
-1. Fork the `xtgeo` repository from the Equinor repository to your GitHub
+1. Fork the XTGeo repository from the Equinor repository to your GitHub
    user account.
 
 2. Clone your fork locally:
@@ -78,7 +72,7 @@ Ready to contribute? Here's how to set up `xtgeo` for local development.
    pip install -e ".[dev,docs]"  # add -vv to see compilation output
    ```
 
-4. Install the test data one directory below your `xtgeo` directory and run
+4. Install the test data one directory below your XTGeo directory and run
    the tests to ensure everything works:
 
    ```sh
@@ -104,16 +98,16 @@ Ready to contribute? Here's how to set up `xtgeo` for local development.
    pytest tests
    ```
 
-7. If you want to edit the C/C++ contact the `xtgeo` authors for detailed
-   instructions.
+7. If you want to contribute to the C/C++ code base contact the XTGeo authors
+   for detailed instructions.
 
-8. Commit your changes
-   (see [Writing commit messages](#writing-commit-messages)) and push your
+8. Commit your changes (see
+   [Writing commit messages](#writing-commit-messages)) and push your
    branch to GitHub:
 
    ```sh
-   git add .
-   git commit -m "ENH: Described changes made"
+   git add file1.py file2.py
+   git commit -m "ENH: Add some feature"
    git push origin name-of-your-bugfix-or-feature
    ```
 
@@ -131,7 +125,6 @@ sphinx-build -W -b html docs build/docs/html
 
 Then open `build/docs/html/index.html` in your browser.
 
-
 ## Writing commit messages
 
 Commit messages should be clear and follow a few basic rules. Example:
@@ -144,26 +137,26 @@ changes X, Y, Z which together completed feature ABC. With this change users
 can now do `vals = values.foo().bar()`.
 ```
 
-The first word of the commit message starts with a capitalized acronym
-(options listed below) indicating what type of commit this is followed by a
-brief description of the change. This line should strive to be less than or
-equal to 50 characters.
+The first word of the commit message starts with a capitalized acronym or
+abbreviation. A list of these is available below. This prefixindicates what
+type of commit this is and is followed by a brief description of the change.
+This line should strive to be less than or equal to 50 characters.
 
 More explanation and context is often helpful to developers in the future. If
 this is the case you should add a blank link with a longer description giving
 some of these contextual details. This commit information can be as long as is
 needed but the individual lines shouldn't be longer than 72 characters.
 
-See [Chris Beams hints on commit messages](https://chris.beams.io/posts/git-commit/)
-for more expalanation of these guidelines.
+See [Chris Beams How to Write a Git Commit Message](https://cbea.ms/git-commit/)
+article for more explanation of these guidelines.
 
 Describing the motivation for a change, the nature of a bug for bug fixes or
 some details on what an enhancement does are also good to include in a commit message.
 Messages should be understandable without looking at the code changes.
-A commit message like FIX: fix another one is an example of what not to do;
+A commit message like `FIX: fix another one` is an example of what not to do;
 the reader has to go look for context elsewhere.
 
-Standard acronyms to start the commit message with are:
+Standard prefixes to start the commit message with are:
 
 ```text
 API: an (incompatible) API change (will be rare)
@@ -183,11 +176,10 @@ TST: addition or modification of tests
 
 ### Type Hints
 
-`xtgeo` requires the use of type annotations in all new feature
+XTGeo requires the use of type annotations in all new feature
 developments, incorporating Python 3.10's enhanced syntax for type hints.
 This facilitates a more concise and readable style.
 
-
 ### Style Guidelines
 
 - For Python versions prior to 3.10, include the following import for
@@ -218,17 +210,16 @@ This facilitates a more concise and readable style.
 Note: These guidelines align with PEP 604 and are preferred for all new code
 submissions and when updating existing code.
 
-
 ## Pull Request Guidelines
 
 Before you submit a pull request, check that it meets these guidelines:
 
 1. The pull request should include tests.
 
 2. If the pull request adds functionality, the docs should be updated. Put
-   your new functionality into a function with a docstring, and add the
-   feature to the list in HISTORY.md.
-
+   your new functionality into a function with a docstring and if it is a
+   public method make sure it displays helpful information in the
+   documentation.
 
 ## Tips
 
@@ -239,9 +230,8 @@ Before you submit a pull request, check that it meets these guidelines:
   ```
 
 - scikit-build-core offers some suggestions about building with editable
-  installs, see info here:
-
-  https://scikit-build-core.readthedocs.io/en/latest/configuration.html#editable-installs
+  installs, see info
+  [here](https://scikit-build-core.readthedocs.io/en/latest/configuration.html#editable-installs)
 
 
 ## Working with RMS python
@@ -250,12 +240,12 @@ The following is a special recipe when working with RMS' Python version,
 and it is targeted to Equinor usage using bash shell in Linux:
 
 ```sh
-unset PYTHONPATH  # to avoid potential issues
 # activate RMS python, e.g. RMS version 13.1.2
 source /prog/res/roxapi/aux/roxenvbash 13.1.2
-# make a virtual env (once):
-python -m venv ~/venv/py38_rms13.1.2
+# Make a venv with the libraries included by RMS
+python -m venv ~/venv/py38_rms13.1.2 --system-site-packages
 source ~/venv/py38_rms13.1.2/bin/activate
+unset PYTHONPATH  # to avoid potential issues
 python -m pip install -U pip
 pip install -e ".[dev]"
 pytest
@@ -264,7 +254,7 @@ pytest
 Now you have an editable install in your virtual environment that can be ran
 in RMS while testing. Hence open rms with ``rms`` command (not ``runrms``).
 
-Inside RMS you can open a Python dialog and run your version of `xtgeo`. Theoretically,
+Inside RMS you can open a Python dialog and run your version of XTGeo. Theoretically,
 you could now do changes in your editable install and RMS should see them.
 However, RMS will not load libraries updates once loaded, and ``importlib.reload``
 will not help very much. One safe alternative is of course to close and
@@ -285,8 +275,6 @@ import xtgeo
 grd = xgeo.grid_from_roxar(project, "Geogrid")
 ```
 
-This will work if you change python code in `xtgeo`. If you change C code in `xtgeo`, then
+This will work if you change python code in XTGeo. If you change C code in XTGeo, then
 this hack will not work. The only solution is to close and re-open RMS everytime the
 C code is compiled.
-
-

docs/conf.py

@@ -12,11 +12,11 @@
 extensions = [
     "autoclasstoc",
     "myst_parser",
+    "sphinx.ext.autodoc",
+    "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.viewcode",
     "sphinx.ext.mathjax",
-    "sphinx.ext.autosummary",
-    "sphinx.ext.autodoc",
     "sphinx_toolbox.more_autosummary",
     "sphinx_autodoc_typehints",
 ]

docs/datamodels.rst

@@ -1,6 +1,5 @@
-=================================
-XTGeo data models and i/o formats
-=================================
+Data model and formats
+======================
 
 Here is a description of the internal datamodels used for various datatypes in
 XTGeo, and the input/output formats that are supported in the current version.

docs/getting_started.rst

@@ -0,0 +1,56 @@
+Getting started
+===============
+
+.. code-block:: python
+
+    import xtgeo
+
+A first step is often to import some object from file. Here we create
+an XTGeo :class:`xtgeo.RegularSurface` with the
+:func:`xtgeo.surface_from_file` function. In this case it defaults to loading
+the file as an IRAP binary file. 
+
+.. code-block:: python
+
+    mysurf = xtgeo.surface_from_file("myfile.gri")
+
+Having an existing file to load from is not required to create
+XTGeo objects, in most cases. They may also be created with directly with
+Python.
+
+.. code-block:: python
+
+    mysurf = xtgeo.RegularSurface(
+        ncol=30, nrow=50, xori=1234.5, yori=4321.0, xinc=30.0, yinc=50.0,
+        rotation=30.0, values=vals, yflip=1,
+    )
+
+The :class:`xtgeo.RegularSurface` class provides many methods to 
+retrieve information about the data contained in this object. Here we print 
+the mean of the values it contains; where ``values`` is a 2D masked numpy array.
+
+.. code-block:: python
+
+    print(f"Mean is {mysurf.values.mean()}")
+
+Because values are stored internally as numpy arrays they can also be operated
+on as you would any numpy array. 
+
+.. code-block:: python
+
+    mysurface.values[mysurface.values < 2000] = 2000
+
+XTGeo also allows data to be operated on as a Pandas dataframe. A robust set
+of convenience methods are given in XTGeo class objects for the operations
+common to reservoir modelling.
+
+Once done you can save and export the modified file. XTGeo has support for
+importing and exporting the most common file formats.
+
+.. code-block:: python
+
+    mysurface.to_file("newfile.gri")
+
+XTGeo has many more capabilities beyond basic value manipulation. For more, 
+check out the examples in the 
+:doc:`Tutorial section <tutorial/tutorial_index>`.

docs/index.rst

@@ -1,25 +1,36 @@
-Welcome to XTGeo's documentation!
-=================================
+Welcome to XTGeo's documentation
+================================
 
 .. figure:: images/xtgeo-logo.png
-     :alt: Logo
-     :width: 300
-     :align: center
+   :alt: Logo
+   :width: 300
+   :align: center
+
+XTGeo is a Python library with a C/C++ backend for efficient manipulation of 
+files and objects used in subsurface reservoir modelling. Typical users are 
+geoscientists and reservoir engineers working with reservoir modelling, 
+particularly with the geomodelling software RMS.
+
+XTGeo is developed and maintained by `Equinor <https://equinor.com>`_.
+
+The repository is hosted on `GitHub <https://github.com/equinor/xtgeo>`_.
 
-Contents
---------
 .. toctree::
    :maxdepth: 1
+   :caption: About
 
-   history
-   readme
    installation
    contributing
+   release_notes
+
+.. toctree::
+   :maxdepth: 1
+   :caption: User guide
+
+   getting_started
+   tutorial/tutorial_index
    datamodels
-   usage
-   usextgeoroxar
    xtgeo_4_migration
-   authors
    apireference
 
 Indices and tables