docs: update documentation

mtrocadomoreira · Nov 12, 2024 · b43f5dc · b43f5dc
1 parent 825b7ab
commit b43f5dc
Show file tree

Hide file tree

Showing 7 changed files with 50 additions and 12 deletions.
diff --git a/...cs/reference/backends/submodules/index.md → docs/docs/dev-guide/new-backend-modules.md b/...cs/reference/backends/submodules/index.md → docs/docs/dev-guide/new-backend-modules.md
diff --git a/docs/docs/reference/backends/index.md b/docs/docs/reference/backends/index.md
@@ -1,5 +1,25 @@
 # Backends
 
+Please navigate to a specific section for more information about the implementation of each simulation file type.
+
+
+<div class="grid cards" markdown>
+
+- [__LCODE__](lcode.md)
+- [__OSIRIS__](osiris.md)
+- [__ozzy__](ozzy.md)
+</div>
+
+If you're looking for the backend-specific methods that you can call on a data object, see the [relevant section of *Data object methods*](../data-objects/backend-methods.md).
+
+## Interface class
+
+!!! info
+
+    This section should only be relevant if you're planning to add support for a new backend or for debugging purposes.
+
+    The `Backend` class serves as an interface between [ozzy's main file-reading functions](../../user-guide/reading-files.md) and the modules for each implemented backend. 
+
 <!-- ## ozzy.backend -->
 
 ::: ozzy.backend_interface
diff --git a/...cs/reference/backends/submodules/lcode.md → docs/docs/reference/backends/lcode.md b/...cs/reference/backends/submodules/lcode.md → docs/docs/reference/backends/lcode.md
@@ -36,4 +36,9 @@ for k, v in oz.backends.lcode_backend.quant_info.items():
         print(f'    units: {v1[1]}')
 ```
 
+## Entry-point `read` function
 
+::: ozzy.backends.lcode_backend
+    options:
+      members:
+      - read
diff --git a/...s/reference/backends/submodules/osiris.md → docs/docs/reference/backends/osiris.md b/...s/reference/backends/submodules/osiris.md → docs/docs/reference/backends/osiris.md
@@ -68,4 +68,11 @@ Some quantities stored in OSIRIS HDF5 files are given specific labels and number
 import ozzy as oz
 print(oz.backends.osiris_backend.special_vars)
 # {'ene': ['$E_{\\mathrm{kin}}$', '$m_\\mathrm{sp} c^2$']}
-```
+```
+
+## Entry-point `read` function
+
+::: ozzy.backends.osiris_backend
+    options:
+      members:
+      - read
diff --git a/...ocs/reference/backends/submodules/ozzy.md → docs/docs/reference/backends/ozzy.md b/...ocs/reference/backends/submodules/ozzy.md → docs/docs/reference/backends/ozzy.md
@@ -1,4 +1,11 @@
 
 # Ozzy backend
 
-When a file is saved via [`Dataset.ozzy.save()`][ozzy.accessors.OzzyDataset.save] or [`DataArray.ozzy.save()`][ozzy.accessors.OzzyDataArray.save], the data and metadata are mapped straightforwardly onto an HDF5 file structure (or NetCDF, if this is the selected format). This backend simply imports the file and ensures that the `'pic_data_type'` and `'data_origin'` are initialized correctly.
+When a file is saved via [`Dataset.ozzy.save()`][ozzy.accessors.OzzyDataset.save] or [`DataArray.ozzy.save()`][ozzy.accessors.OzzyDataArray.save], the data and metadata are mapped straightforwardly onto an HDF5 file structure (or NetCDF, if this is the selected format). This backend simply imports the file and ensures that the `'pic_data_type'` and `'data_origin'` are initialized correctly.
+
+## Entry-point `read` function
+
+::: ozzy.backends.ozzy_backend
+    options:
+      members:
+      - read
diff --git a/docs/docs/reference/data-objects/data-type-methods.md b/docs/docs/reference/data-objects/data-type-methods.md
@@ -15,12 +15,12 @@ These methods can be accessed via the standard [accessor](index.md) way, i.e.:
     ```
 
 ??? note "Note for developers"
-    These methods are defined within specific mixin classes: `GridMixin` (`grid_mixin.py`) and `PartMixin` (`part_mixin.py`).
+    The following methods are defined within specific mixin classes: `GridMixin` (`grid_mixin.py`) and `PartMixin` (`part_mixin.py`).
 
-=== "Grid data"
+## Grid data
 
-    ::: ozzy.grid_mixin
+::: ozzy.grid_mixin
 
-=== "Particle data"
+## Particle data
 
-    ::: ozzy.part_mixin
+::: ozzy.part_mixin
diff --git a/docs/mkdocs.yml b/docs/mkdocs.yml
@@ -115,6 +115,7 @@ repo_url: https://github.com/mtrocadomoreira/ozzy
 
 plugins:
   - search
+  - autorefs
  # - privacy # mathjax equations are not rendered correctly when this is active
   - mkdocstrings:
       default_handler: python
@@ -197,11 +198,9 @@ nav:
       - Backend-specific methods: reference/data-objects/backend-methods.md
     - Backends: 
       - reference/backends/index.md
-      - Submodules: 
-        - reference/backends/submodules/index.md
-        - LCODE: reference/backends/submodules/lcode.md
-        - OSIRIS: reference/backends/submodules/osiris.md
-        - Ozzy: reference/backends/submodules/ozzy.md
+      - LCODE: reference/backends/lcode.md
+      - OSIRIS: reference/backends/osiris.md
+      - ozzy: reference/backends/ozzy.md
     - ozzy.plot: reference/plot.md
     - ozzy.statistics: reference/statistics.md
     - ozzy.fields: reference/fields.md