Merge pull request #583 from DHI/docs

Updated docs after reorg

.github/workflows/build_docs.yml

@@ -0,0 +1,33 @@
+name: Build documentation (don't publish)
+
+on:
+  push:
+    pull_request:
+      branches: [ main ]
+
+jobs:
+  build:
+
+    runs-on: ubuntu-latest
+
+    steps:
+    - uses: actions/checkout@v2
+    - name: Set up Python 3.10
+      uses: actions/setup-python@v2
+      with:
+        python-version: "3.10"
+
+    - name: Install MIKE IO
+      run: |
+        pip install .[dev]
+    
+    - name: Sphinx Build
+      run: |
+        cd docs
+        make html
+
+    - name: Upload documentation
+      uses: actions/upload-artifact@v2
+      with:
+        name: html
+        path: docs/_build/html

.gitignore

@@ -25,4 +25,5 @@ cov_annotate
 htmlcov
 
 docs/_build
-\tmp
+\tmp
+.venv/

docs/conf.py

@@ -18,8 +18,8 @@
 # -- Project information -----------------------------------------------------
 
 project = "MIKE IO"
-copyright = "2022, Henrik Andersson, Jesper Mariegaard, Marc Ridler,"
-author = "Henrik Andersson, Jesper Mariegaard, Marc Ridler"
+copyright = "2023, DHI"
+author = "Henrik Andersson, Jesper Mariegaard"
 release = ""
 
 # -- General configuration ---------------------------------------------------
@@ -37,6 +37,19 @@
     "myst_parser",
 ]
 
+# inspired by https://github.com/pydata/xarray/blob/main/doc/conf.py
+
+autodoc_typehints = "none"
+
+# Napoleon configurations
+
+napoleon_google_docstring = False
+napoleon_numpy_docstring = True
+napoleon_use_param = False
+napoleon_use_rtype = False
+napoleon_preprocess_types = True
+
+
 # Configuration to include links to other project docs when referencing
 # functions/classes
 intersphinx_mapping = {

docs/data-structures.md

@@ -2,8 +2,8 @@
 
 MIKE IO has these primary data structures: 
 
-* [Dataset](Dataset) - a collection of DataArrays corresponding to the contents of a dfs file; typically obtained from {py:meth}`mikeio.read`
-* [DataArray](DataArray) - data and metadata corresponding to one "item" in a dfs file. 
+* [**Dataset**](Dataset) - a collection of DataArrays corresponding to the contents of a dfs file; typically obtained from {py:meth}`mikeio.read`
+* [**DataArray**](DataArray) - data and metadata corresponding to one "item" in a dfs file. 
 * **Geometry** - spatial description of the data in a dfs file; comes in different flavours: [Grid1D](Grid1D), [Grid2D](Grid2D), [Grid3D](Grid3D), [GeometryFM](GeometryFM), [GeometryFM3D](GeometryFM3D), etc. corresponding to different types of dfs files. 
-* **Dfs** - an object returned by `dfs = mikeio.open()` containing the metadata (=header) of a dfs file ready for reading the data (which can be done with `dfs.read()`); exists in different specialized versions: [Dfs0](Dfs0), [Dfs1](Dfs1), [Dfs2](Dfs2), [Dfs3](Dfs3), [Dfsu2DH](Dfsu2DH), [Dfsu3D](Dfsu3D), [Dfsu2DV](Dfsu2DV), [DfsuSpectral](DfsuSpectral), 
+* **Dfs** - an object returned by `dfs = mikeio.open()` containing the metadata (=header) of a dfs file ready for reading the data (which can be done with `dfs.read()`); exists in different specialized versions: [Dfs0](Dfs0), [Dfs1](Dfs1), [Dfs2](Dfs2), [Dfs3](Dfs3), [Dfsu2DH](Dfsu2DH), [Dfsu3D](Dfsu3D), [Dfsu2DV](Dfsu2DV), [DfsuSpectral](DfsuSpectral).
 

docs/dataarray.md

@@ -1,6 +1,6 @@
 # DataArray
 
-The [DataArray](DataArray) is the common MIKE IO data structure 
+The [DataArray](mikeio.DataArray) is the common MIKE IO data structure 
 for *item* data from dfs files. 
 The {py:meth}`mikeio.read` methods returns a Dataset as a container of DataArrays (Dfs items)
 
@@ -98,7 +98,7 @@ The plotting of a DataArray is context-aware meaning that plotting behaviour dep
 >>> da.plot.mesh()
 ```
 
-See details in the [API specification](_DatasetPlotter) below and in the bottom of the relevant pages e.g. [DataArray Plotter Grid2D API](_DataArrayPlotterGrid2D) on the dfs2 page.
+See details in the [API specification](mikeio.dataset._data_plot._DataArrayPlotter) below and in the bottom of the relevant pages e.g. [DataArray Plotter Grid2D API](dfs2.md#dataarray-plotter-grid2d-api) on the dfs2 page.
 
 
 
@@ -175,7 +175,7 @@ Other methods that also return a DataArray:
 A DataArray `da` can be plotted using `da.plot`. 
 
 ```{eval-rst}
-.. autoclass:: mikeio.dataarray._DataArrayPlotter
+.. autoclass:: mikeio.dataset._data_plot._DataArrayPlotter
 	:members:
 ```
 

docs/dataset.md

@@ -1,8 +1,8 @@
 # Dataset
 
-The [Dataset](Dataset) is the MIKE IO data structure 
+The [Dataset](mikeio.Dataset) is the MIKE IO data structure 
 for data from dfs files. 
-The {py:meth}`mikeio.read` methods returns a Dataset as a container of [DataArrays](dataarray) (Dfs items). Each DataArray has the properties, *item*, *time*, *geometry* and *values*. The time and geometry are common to all DataArrays in the Dataset. 
+The {py:meth}`mikeio.read` methods returns a Dataset as a container of [DataArrays](mikeio.DataArray) (Dfs items). Each DataArray has the properties, *item*, *time*, *geometry* and *values*. The time and geometry are common to all DataArrays in the Dataset. 
 
 The Dataset has the following primary properties: 
 
@@ -113,7 +113,7 @@ In most cases, you will *not* plot the Dataset, but rather it's DataArrays. But
 * dfs0-Dataset : plot all items as timeseries with ds.plot()
 * scatter : compare two items using ds.plot.scatter(x="itemA", y="itemB")
 
-See details in the [API specification](_DatasetPlotter) below.
+See details in the [API specification](Dataset Plotter API) below.
 
 
 ## Properties
@@ -189,7 +189,7 @@ Other methods that also return a Dataset:
 ## Dataset Plotter API
 
 ```{eval-rst}
-.. autoclass:: mikeio.dataset._DatasetPlotter
+.. autoclass:: mikeio.dataset._data_plot._DatasetPlotter
 	:members:
 ```
 

docs/design.md

@@ -1,13 +1,13 @@
 # Design philosophy
 
-* Easy to use
-* Familiar
-* Easy to install
-* Easy to get started
-* Open Source​
-* Easy to collaborate​
-* Reproducible
-* Easy access to new features
+* [Easy to use](#easy-to-use)
+* [Familiar](#familiar)
+* [Easy to install](#easy-to-install)
+* [Easy to get started](#easy-to-get-started)
+* [Open Source​](#open-source)
+* [Easy to collaborate​](#easy-to-collaborate)
+* [Reproducible](#reproducible)
+* [Easy access to new features](#easy-access-to-new-features)
 
 
 ## Easy to use
@@ -23,9 +23,9 @@ MIKE IO aims to use a syntax familiar to users of scientific computing libraries
 
 ## Easy to install
 
-From PyPI::
-
-    pip install mikeio
+```bash
+$ pip install mikeio
+```
 
 ## Easy to get started
 By providing many examples to cut/paste from.
@@ -47,18 +47,18 @@ By developing MIKE IO on GitHub along with a completely open discussion, we beli
 ## Reproducible
 By providing the historical versions of MIKE IO on PyPI it is possible to reproduce the behaviour of an older existing system, based on an older version.
 
-Install specific version::
+**Install specific version**
 
-```
-pip install mikeio==0.12.2
+```bash
+pip install mikeio==1.4.0
 ```
 
 ## Easy access to new features
 Features are being added all the time, by developers at DHI in offices all around the globe as well as external contributors using MIKE IO in their work.
-These new features are always available from the main branch on GitHub and thanks to automated testing, it is always possible to verify that the tests passes before downloading a new development version.
+These new features are always available from the [main branch on GitHub](https://github.com/DHI/mikeio) and thanks to automated testing, it is always possible to verify that the tests passes before downloading a new development version.
 
-Install development version::
+**Install development version**
 
-```
-pip install https://github.com/DHI/mikeio/archive/main.zip
+```bash
+$ pip install https://github.com/DHI/mikeio/archive/main.zip
 ```

docs/dfs-overview.md

@@ -8,12 +8,12 @@
 All Dfs classes (and the Dataset) class are representations of timeseries and 
 share these properties: 
 
-* items - a list of [ItemInfo](ItemInfo) with name, type and unit of each item
+* items - a list of [ItemInfo](mikeio.eum._eum.ItemInfo) with name, type and unit of each item
 * n_items - Number of items
 * n_timesteps - Number of timesteps
 * start_time - First time instance (as datetime)
 * end_time - Last time instance (as datetime)
-* geometry - spatial description of the data in the file ([Grid1D](Grid1D), [Grid2D](Grid2D), etc ... )
+* geometry - spatial description of the data in the file ([Grid1D](mikeio.Grid1D), [Grid2D](mikeio.Grid2D), etc ... )
 * deletevalue - File delete value (NaN value)
 
 
@@ -30,5 +30,6 @@ If the file is big, you will typically get the file *header* with `dfs = mikeio.
 
 ```{eval-rst}
 .. automodule:: mikeio
-	:members:
+	:members: read, open
+
 ```

docs/dfs1.md

@@ -17,7 +17,7 @@ items:
 
 ## Grid 1D
 
-The spatial information is available in the `geometry` attribute (accessible from Dfs1, Dataset, and DataArray), which in the case of a dfs1 file is a [`Grid1D`](Grid1D) geometry. 
+The spatial information is available in the `geometry` attribute (accessible from Dfs1, Dataset, and DataArray), which in the case of a dfs1 file is a [`Grid1D`](mikeio.Grid1D) geometry. 
 
 ```python
 >>> ds.geometry
@@ -33,7 +33,7 @@ Grid1D's primary properties and methods are:
 * `find_index()`
 * `isel()`
 
-See [API specification](Grid1D) below for details.
+See [API specification](mikeio.Grid1D) below for details.
 
 
 
@@ -60,7 +60,7 @@ See [API specification](Grid1D) below for details.
 A DataArray `da` with a Grid1D geometry can be plotted using `da.plot`. 
 
 ```{eval-rst}
-.. autoclass:: mikeio.dataarray._DataArrayPlotterGrid1D
+.. autoclass:: mikeio.dataset._data_plot._DataArrayPlotterGrid1D
 	:members:
 	:inherited-members:
 ```

docs/dfs2.md

@@ -19,7 +19,7 @@ items:
 
 ## Grid2D
 
-The spatial information is available in the `geometry` attribute (accessible from Dfs2, Dataset, and DataArray), which in the case of a dfs2 file is a [`Grid2D`](Grid2D) geometry. 
+The spatial information is available in the `geometry` attribute (accessible from Dfs2, Dataset, and DataArray), which in the case of a dfs2 file is a [`Grid2D`](mikeio.Grid2D) geometry. 
 
 ```python
 >>> ds.geometry
@@ -46,7 +46,7 @@ Grid2D's primary properties and methods are:
 * `isel()`
 * `to_mesh()`
 
-See [API specification](Grid2D) below for details.
+See [API specification](mikeio.Grid2D) below for details.
 
 
 ## Dfs2 Example notebooks
@@ -81,7 +81,7 @@ See [API specification](Grid2D) below for details.
 A DataArray `da` with a Grid2D geometry can be plotted using `da.plot`. 
 
 ```{eval-rst}
-.. autoclass:: mikeio.dataarray._DataArrayPlotterGrid2D
+.. autoclass:: mikeio.dataset._data_plot._DataArrayPlotterGrid2D
 	:members:
 	:inherited-members:
 ```

docs/dfsu-1dv-vertical-column.md

@@ -6,7 +6,7 @@
 ## FM Geometry Vertical Column API
 
 ```{eval-rst}
-.. autoclass:: mikeio.spatial.FM_geometry.GeometryFMVerticalColumn
+.. autoclass:: mikeio.spatial._FM_geometry_layered.GeometryFMVerticalColumn
 	:members:
 	:inherited-members:
 ```

docs/dfsu-2d.md

@@ -5,7 +5,7 @@
 
 A Dfsu class (e.g. Dfsu2DH) is returned by {py:meth}`mikeio.open` if the argument is a dfsu file. 
 
-Apart from the common [dfsu-geometry properties and methods](./dfu-mesh-overview.md#mike-io-flexible-mesh-geometry), Dfsu2DH has the following *properties*:
+Apart from the common [dfsu-geometry properties and methods](MIKE IO Flexible Mesh Geometry), Dfsu2DH has the following *properties*:
 
 
 ```{eval-rst}
@@ -34,7 +34,7 @@ Dfsu2DH has the following *methods*:
     mikeio.dfsu._Dfsu.close
 ```
 
-See the [API specification](Dfsu2DH) below for a detailed description. 
+See the [API specification](Dfsu 2DH API) below for a detailed description. 
 
 See the [Dfsu Read Example notebook](https://nbviewer.jupyter.org/github/DHI/mikeio/blob/main/notebooks/Dfsu%20-%20Read.ipynb) for basic dfsu functionality.
 
@@ -51,19 +51,20 @@ See the [Dfsu Read Example notebook](https://nbviewer.jupyter.org/github/DHI/mik
 
 ## Flexible Mesh Geometry API
 
-See [Flexible Mesh Geometry API](GeometryFM)
+See [Flexible Mesh Geometry API](mikeio.spatial.GeometryFM2D)
 
-
-## FM Geometry Plotter API
-
-See [FM Geometry Plotter API](_GeometryFMPlotter)
+```{eval-rst}
+.. autoclass:: mikeio.spatial.GeometryFM2D
+    :members:
+    :inherited-members:
+```
 
 ## DataArray Plotter FM API
 
 A DataArray `da` with a GeometryFM geometry can be plotted using `da.plot`. 
 
 ```{eval-rst}
-.. autoclass:: mikeio.dataarray._DataArrayPlotterFM
+.. autoclass:: mikeio.dataset._data_plot._DataArrayPlotterFM
 	:members:
 	:inherited-members:
 ```