Merge pull request #838 from nicolasaunai/doc

update documentation

Author: nicolasaunai

doc/source/conf.py

@@ -21,7 +21,7 @@
 # -- Project information -----------------------------------------------------
 
 project = "PHARE"
-copyright = "2018-2023, Nicolas Aunai, Roch Smets, Philip Deegan"
+copyright = "2018-2024, Nicolas Aunai, Roch Smets, Philip Deegan"
 author = "Nicolas Aunai, Roch Smets, Philip Deegan"
 
 # The short X.Y version
@@ -43,22 +43,20 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.mathjax",
     "sphinx.ext.githubpages",
-    "sphinx.ext.autodoc",
     "sphinx.ext.viewcode",
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.autosectionlabel",
     "sphinx_gallery.load_style",
     "sphinx_codeautolink",
-    "sphinxcontrib.apidoc",
     "nbsphinx",
-    "numpydoc",
 ]
-apidoc_module_dir = "../../pyphare"
-apidoc_output_dir = "development"
-apidoc_separate_modules = True
-apidoc_module_first = True
 
+autodoc_default_options = {
+    "members": True,
+    "private-members": False,
+    "special-members": False,
+}
 
 autosectionlabel_prefix_document = True
 codeautolink_custom_blocks = {
@@ -104,7 +102,8 @@
 exclude_patterns = []
 
 # The name of the Pygments (syntax highlighting) style to use.
-pygments_style = None
+# pygments_style = None
+pygments_style = "sphinx"
 
 
 # -- Options for HTML output -------------------------------------------------

doc/source/development/tests.rst

@@ -20,6 +20,7 @@ Using Adaptive Mesh Refinement, provided by the library SAMRAI, PHARE aims at
 filling the gap between sub-ion scales and large "MHD" scales by increasing
 the mesh resolution wherever the solution needs it.
 
+Warning: This documentation is a work in progress. It is not complete and may contain errors.
 
 
 .. raw:: html
@@ -76,9 +77,9 @@ the mesh resolution wherever the solution needs it.
    :maxdepth: 1
    :hidden:
 
+   usage/simulation_inputs
    usage/run_from_python
    usage/run_from_exe
-   usage/simulation_inputs
    usage/examples
 
 
@@ -98,14 +99,6 @@ the mesh resolution wherever the solution needs it.
 
 
 
-.. Development
-.. -----------
-.. toctree::
-   :caption: DEVELOPMENT
-   :maxdepth: 1
-   :hidden:
-
-   development/tests
 
 .. Indices and tables
 .. ------------------

doc/source/index.rst

@@ -3,21 +3,100 @@
 Data analysis
 =============
 
+pharesee
+--------
+
+The data produced by phare is readable with the `pharesee` python package from
+the `pyphare`. Make your `PYTHONPATH` includes the directory where `pyphare` is located.
+
+.. code-block:: bash
+
+    export PYTHONPATH=$PYTHONPATH:/path/to/PHARE/pyphare
+
+
+Then import the `pharesee` package should work:
+
+.. code-block:: python
+
+    import pyphare.pharesee as pharesee
+
+
+
+Reading the data
+----------------
+
+We will imagine a situation where you have run a simulation
+for which `ElectromagDianostics` have been activated and you want to get the magnetic field. Assuming the data is in:
+
+.. code-block:: bash
+
+    /data/scratch/phare_jobs/run001/
+
+
+The first step to get the data is to create a `Run` object, that basically represents
+your simulation and will let you interact with its data.
+
+.. code-block:: python
+
+    from pyphare.pharesee.run import Run
+
+    path = "/data/scratch/phare_jobs/run001/"
+    run = Run(path)
+
+
+Getting data is then done by calling methods of that `run` instance you just created.
+Every data getters takes the same form:
+
+.. code-block:: python
+
+    run.GetXXX(time)
+
+where `XXX` is the name of a physical quantity available from `pharesee`, 
+and `time` is the time at which you want to get the data.
+
+For example, to get the magnetic field at time 0.0:
+
+.. code-block:: python
+
+    B = run.GetB(0.0)
 
-Getting Data
-============
 
 
 
 Python Patch Hierarchy
-======================
+----------------------
+
+Generalities
+^^^^^^^^^^^^
+
+The data read from a run most often takes the form of a `PatchHierarchy` instance.
+This python object represents the hierarchy of levels of patches where the data lies.
+
+.. code-block:: python
+
+    B = run.GetB(0.0)  # B is a PatchHierarchy
+
+
+See section :ref:
+
+
+Advanced usage
+^^^^^^^^^^^^^
 
 
 
 Using the finest field available
-================================
+--------------------------------
+
+
 
 
+The Run methods
+---------------
 
+.. autoclass:: pyphare.pharesee.run.Run
+    :members:
+    :undoc-members:
+    :show-inheritance: