Update documentation

README.md

@@ -15,7 +15,7 @@
 * [**Documentation**](https://equinor.github.io/subscript)
 * [**Installation**](#installation)
 * [**Usage**](#usage)
-* [**Contribution**](https://equinor.github.io/subscript/contribution.html)
+* [**Contributing**](https://equinor.github.io/subscript/contributing.html)
 
 ---
 
@@ -38,10 +38,10 @@ Note that some of these utilities may depend upon commercial third-party
 software.
 
 
-## Developing & Contribution
+## Developing & Contributing
 
 All contributions are welcome. Please see the
-[Contribution document](https://equinor.github.io/subscript/contribution.html)
+[Contributing document](https://equinor.github.io/subscript/contributing.html)
 for more details and instructions for getting started.
 
 

docs/conf.py

@@ -19,7 +19,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "subscript"
-copyright = "2020, Equinor"
+copyright = "Equinor"
 author = "Equinor"
 
 import subscript  # noqa
@@ -47,6 +47,7 @@
 # ones.
 extensions = [
     "autoapi.sphinx",
+    "sphinx_copybutton",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
     "sphinx.ext.inheritance_diagram",

docs/contributing.rst

@@ -0,0 +1,111 @@
+Contributing
+============
+
+Thanks for considering contributing to subscript! All contributions are
+welcome. This document is meant to help you get started and contains some
+guidelines that must be met before a contribution can be accepted.
+
+
+Getting started
+---------------
+
+We recommend developing from a personal fork rather than branches on the
+upstream repository. Create a fork from the repository and then clone it 
+to your machine:
+
+.. code-block:: console
+
+  git clone git@github.com:<youraccount>/subscript
+  cd subscript
+
+Then add the upstream repository:
+
+.. code-block:: console
+
+  git remote add upstream git@github.com:equinor/subscript
+
+After cloning, you need a Python virtual environment in which you install 
+subscript and its dependencies. If you develop on an Equinor computer you
+should use ``komodoenv``; instructions for how to do this can be found
+`here <https://fmu-docs.equinor.com/docs/komodo/equinor_komodo_usage.html>`
+(internal). Otherwise, set up a normal virtual environment.
+
+.. code-block:: console
+
+  python3 -m venv venv-subscript
+  source venv-subscript/bin/activate  # append ".csh" if c-shell
+
+and then upgrade and install the dependencies with ``pip``:
+
+.. code-block:: console
+
+  pip install -U pip
+  pip install -e ".[tests,docs]"
+
+to install subscript in "edit"-mode together will all the dependencies for
+subscript, its test suite, and documentation dependencies.
+
+A good start is to verify that all tests pass after having cloned the
+repository, which you can do by running:
+
+.. code-block:: console
+
+  pytest -n auto
+
+If you want to run the full test-suite within the Equinor Linux environment
+you can invoke the test run in the following manner. This will include
+running tests that rely upon a black oil simulation.
+
+.. code-block:: console
+
+  pytest -n --flow-simulator="/project/res/x86_64_RH_7/bin/flowdaily" --eclipse-simulator="runeclipse"
+
+
+Code style
+----------
+
+Before making a pull request you should verify that your changes will pass
+the linting done in CI:
+
+ .. code-block:: console
+
+  isort --check-only --profile black src tests
+  black --check *.py src tests
+  flake8 src tests
+  mypy src/subscript
+  rstcheck -r docs
+
+
+Documentation
+-------------
+
+Ensure the documentation is up-to-date with your changes. You can build and
+view the documentation like so:
+
+ .. code-block:: console
+
+  sphinx-build -b html docs build/docs/html
+  firefox build/docs/html/index.html
+
+
+Repository conventions
+----------------------
+
+* Each tool has its own subdirectory under ``src/subscript``.
+* Use ``pyproject.toml`` for installing endpoints that users should have in 
+  their ``$PATH``
+* Use ``argparse``, and with a specific ``get_parser()`` function to facilitate 
+  ``sphinx-argparse``
+* Always use the ``if __name__ = "__main__"`` idiom. Scripts should not start 
+  if they are imported, this is to facilitate testing.
+* There must be at least test code that directly test that the endpoint is 
+  installed and that it does at least something to a standard input. Preferably
+  unit test code for isolated parts of the code as well.
+* Docstrings on all functions. Docstrings can include RST formatting and will
+  be checked for compliance with sphinx on every pull request. Warnings from 
+  sphinx must be fixed.
+* For a new script, write a new file ``docs/scripts/scriptname.rst`` describing
+  the script, its usage, and examples. Use sphinx-argparse to document the 
+  command line syntax.
+* Type hinting is encouraged. If type hinting is included in the source, it has
+  to pass mypy.

docs/index.rst

@@ -1,8 +1,8 @@
 *********
-Subscript
+subscript
 *********
 
-Subscript is an Equinor collection of scripts used for subsurface reservoir
+subscript is Equinor's collection of scripts used for subsurface reservoir
 modelling.
 
 .. include::
@@ -12,7 +12,8 @@ modelling.
    :glob:
    :maxdepth: 1
 
-   contribution.rst
+   overview.rst
+   contributing.rst
    history.rst
 
 .. toctree::

docs/overview.rst

@@ -0,0 +1,43 @@
+Overview
+========
+
+Here is a summary of the scripts included in this package and how they can
+be used.
+
+========================  ===  =================  ============
+Script                    CLI  ERT Forward Model  ERT Workflow
+========================  ===  =================  ============
+bjobsusers                ✅   ⛔️                 ⛔️
+casegen_upcars            ✅   ⛔️                 ⛔️
+check_swatinit            ✅   ✅                 ⛔️
+co2_containment           ✅   ⛔️                 ⛔️
+convert_grid_format [*]_  ✅   ✅                 ⛔️
+csv2ofmvol                ✅   ✅                 ⛔️
+csv_merge                 ✅   ⛔️                 ✅
+csv_stack                 ✅   ✅                 ✅
+eclcompress               ✅   ✅                 ⛔️
+ecldiff2roff              ✅   ✅                 ⛔️
+fmu_copy_revision         ✅   ⛔️                 ⛔️
+fmuobs                    ✅   ⛔️                 ✅
+interp_relperm            ✅   ✅                 ⛔️
+merge_rft_ertobs          ✅   ✅                 ⛔️
+ofmvol2csv                ✅   ✅                 ⛔️
+pack_sim                  ✅   ⛔️                 ⛔️
+params2csv                ✅   ✅                 ✅
+presentvalue              ✅   ⛔️                 ⛔️
+prtvol2csv                ✅   ✅                 ⛔️
+restartthinner            ✅   ⛔️                 ⛔️
+ri_wellmod                ✅   ✅                 ⛔️
+rmsecl_volumetrics        ✅   ⛔️                 ⛔️
+runrms                    ✅   ⛔️                 ⛔️
+sector2fluxnum            ✅   ⛔️                 ⛔️
+summaryplot               ✅   ⛔️                 ⛔️
+sw_model_utilities        ✅   ⛔️                 ⛔️
+sunsch                    ✅   ✅                 ⛔️
+vfp2csv                   ✅   ⛔️                 ⛔️
+welltest_dpds             ✅   ✅                 ⛔️
+========================  ===  =================  ============
+
+.. [*] ``convert_grid_format`` is the script that contains functionality
+   for the ``ECLGRID2ROFF``, ``ECLINIT2ROFF``, and ``ECLRST2ROFF`` forward 
+   models.

docs/usage.rst

@@ -2,13 +2,13 @@ Using subscript
 ===============
 
 In Equinor, all subscript utilities are installed on all Linux
-computers, and are available in every users path when Komodo is activated::
+computers and are available in every user's path when Komodo is activated::
 
   source /prog/res/komodo/stable/enable.csh
 
 Remove the ``.csh`` from the line above if you are using *bash* (recommended).
 
-For installation on non-Equinor computers, create and activate a Python3
+For installation on non-Equinor computers, create and activate a Python
 virtual environment and run::
 
-  pip install git+https://github.com/equinor/subscript
+  pip install subscript

pyproject.toml

@@ -80,6 +80,7 @@ docs = [
     "sphinx<7",
     "sphinx-argparse",
     "sphinx-autodoc-typehints",
+    "sphinx-copybutton",
     "sphinx_rtd_theme",
 ]