Small changes

Author: lisajulia

python/sphinx_docs/docs/common.rst

@@ -1,4 +1,22 @@
 OPM Common Python Documentation
 ===============================
 
+Note on Import Paths
+--------------------
+
+In this documentation, you may notice that some classes are referenced with their full import paths (e.g., opm.io.deck.DeckItem), while others are shown with just the class name. This distinction reflects how these classes are structured within the package:
+
+- Fully Qualified Paths: Classes displayed with their full import paths can be directly imported from their respective modules. For example:
+.. code-block:: python
+
+    from opm.io.deck import DeckItem
+
+
+- Simplified Class Names: Classes displayed with just their names, e.g. Connectoin, are intended for internal use or may require additional context when importing. Refer to the specific module documentation for the correct import path if needed.
+
+This structure allows for a organized and modular package, helping to easily access commonly used classes while maintaining clarity for internal components.
+
+Documentation
+-------------
+
 .. opm_common_docstrings::

python/sphinx_docs/docs/flow-in-python.rst

@@ -36,18 +36,16 @@ If you installed in a non-standard directory by specifying -DCMAKE_INSTALL_PREFI
 
 		PYTHONPATH=/opt/opm/lib/python3.11/site-packages python3 spe1case1.py
 
-Here, spe1case1.py could be:
+Here, the example script spe1case1.py could be:
 
 .. code-block:: python
 
-		import os
 		from opm.simulators import BlackOilSimulator
 		from opm.io.parser import Parser
 		from opm.io.ecl_state import EclipseState
 		from opm.io.schedule import Schedule
 		from opm.io.summary import SummaryConfig
 
-		os.chdir("SPE1CASE1")
 		deck  = Parser().parse('SPE1CASE1.DATA')
 		state = EclipseState(deck)
 		schedule = Schedule( deck, state )
@@ -61,3 +59,5 @@ Here, spe1case1.py could be:
 		sim.set_porosity(poro)
 		sim.step()
 		sim.step_cleanup()
+
+where you could use the SPE1CASE1.DATA file from `the opm-test repository <https://github.com/OPM/opm-tests/tree/master/spe1>`_.

python/sphinx_docs/docs/index.rst

@@ -7,6 +7,11 @@ There are two Python APIs within OPM Flow:
 - running a Python script embedded in a simulation (see :doc:`embedded-python`)
 
 
+This site further contains the documentation of:
+
+- the classes available from OPM Common (see :doc:`common`)
+- the classes available from OPM Simulators (see :doc:`simulators`)
+
 Contents
 ========
 .. toctree::

python/sphinx_docs/docs/simulators.rst

@@ -1,4 +1,18 @@
 OPM Simulators Python Documentation
 ===================================
 
+Note on Import Paths
+--------------------
+
+In this documentation, the BlackOilSimulator class is referenced with its full import path, i.e., opm.simulators.BlackOilSimulator. This reflects how the BlackOilSimulator class can be imported:
+
+.. code-block:: python
+
+    from opm.simulators import BlackOilSimulator
+
+
+Documentation
+-------------
+
+
 .. opm_simulators_docstrings::