DOC: solve issues in documentation

Author: jcrivenaes

CONTRIBUTING.md

@@ -9,7 +9,7 @@ You can contribute in many ways:
 
 ### Report Bugs
 
-Report issues and bugs at https://github.com/equinor/fmu-config/issues
+Report issues and bugs at [fmu-config/issues](https://github.com/equinor/fmu-config/issues)
 
 If you are reporting a bug, please include:
 
@@ -35,8 +35,7 @@ articles, and such.
 
 ### Submit Feedback
 
-The best way to send feedback is to file an issue
-at https://github.com/equinor/fmu-config/issues.
+The best way to send feedback is to file an issue at [fmu-config/issues](https://github.com/equinor/fmu-config/issues)
 
 If you are proposing a feature:
 
@@ -51,15 +50,13 @@ It is very important to be complient to code standards. fmu-config uses
 [ruff](https://pypi.org/project/ruff/),
 [mypy](https://mypy.readthedocs.io/en/stable/) to format and lint all code.
 
-
-### In addition:
+### In addition
 
 - Start with documentation and tests. Think and communicate first!
 - Docstrings shall start and end with """ and use Google style.
 - Use pytest as testing engine
 - Code shall be be Python 3.9+ compliant
 
-
 ### Linting
 
 ```sh
@@ -72,12 +69,13 @@ The pylint is rather strict and sometimes excpetions are needed... , but anyway
   python -m pylint mycode.py
 ```
 
-## Get Started!
+## Get Started
 
 Ready to contribute? Here's how to set up `fmu-config` for local development.
 
 1. Fork the `fmu-config` repo in web browser to a personal fork
 2. Clone your fork locally:
+
     ```sh
         git clone git@github.com:<your-user>/fmu-config.git
         cd fmu-config
@@ -87,6 +85,7 @@ Ready to contribute? Here's how to set up `fmu-config` for local development.
    This means your `origin` is now your personal fork, while the actual master
    is at `upstream`.
 3. Then create a virtual environment and install
+
     ```sh
         python -m venv <your-venv>
         source <your-venv>/bin/activate

docs/examples.rst

@@ -59,19 +59,19 @@ IPL example
 """""""""""
 .. code-block:: text
 
-   Include("../input/global_variables/global_variables.ipl")
+   Include("../../fmuconfig/output/global_variables.ipl")
 
-   FOR i FROM 1 TO TOP_LOBE.length DO
+   FOR i FROM 1 TO TOP_LOBES.length DO
        Print("Reading ", TOP_LOBE[i])
 
 
-Python example
-""""""""""""""
+Python example (using yaml_load)
+""""""""""""""""""""""""""""""""
 .. code-block:: python
 
    import fmu.config.utilities as utils
 
-   cfg = utils.yaml_load('../input/global_variables/global_variables_rms.yml')
+   CFG = utils.yaml_load('../../fmuconfig/output/global_variables.yml')
 
-   for toplobe in cfg['horizons']['TOP_LOBE']:
+   for toplobe in CFG["rms"]["horizons"]["TOP_LOBES"]:
        print('Working with {}'.format(toplobe))

docs/index.rst

@@ -11,12 +11,7 @@ Welcome to fmu-config's documentation!
    examples
    contributing
 
-API
-===
 
-.. toctree::
-
-   fmu.config/fmu.config
 
 Indices and tables
 ==================

docs/usage.rst

@@ -105,3 +105,30 @@ need to initiate the Class instance and run a few methods. Here is an example:
    if __name__ == "__main__":
       cleanup()
       main()
+
+Using the output YAML in RMS or scripts
+---------------------------------------
+
+.. code-block:: python
+
+   from fmu.config import utilities as util
+
+   CONFIG = "../../fmuconfig/output/global_variables.yml"
+
+   CFG = util.yaml_load(CONFIG)
+
+
+Loading the input YAML in RMS or scripts
+----------------------------------------
+
+In some cases we may need to load the 'input' version of the YAML files which in fmu.config has
+a syntax (e.g. the ``!include`` keys) which makes it not compatible with the YAML standard.
+The solution then is to use a ``loader="FMU"`` key-value:
+
+.. code-block:: python
+
+   from fmu.config import utilities as util
+
+   CONFIG = "../../fmuconfig/input/global_master_variables.yml"
+
+   CFG = util.yaml_load(CONFIG, loader="FMU")