Various minor improvements of documentation (capytaine#430)

jnvn7 · Nov 24, 2023 · c626030 · c626030
1 parent f6a6e85
commit c626030
Show file tree

Hide file tree

Showing 4 changed files with 16 additions and 10 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -58,6 +58,11 @@
     "pull": ("https://github.com/capytaine/capytaine/pull/%s", "PR %s"),
 }
 
+rst_prolog = f"""
+.. |examples_folder| replace:: Github folder with examples for version {__version__}
+.. _examples_folder: https://github.com/capytaine/capytaine/tree/v{__version__}/docs/user_manual/examples/
+"""
+
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 

diff --git a/docs/index.rst b/docs/index.rst
@@ -1,6 +1,6 @@
-===============================================
-Capytaine: a Python-based distribution of Nemoh
-===============================================
+==========================================================
+Capytaine: a Python-based linear potential flow BEM solver
+==========================================================
 
 Capytaine is a Python package for the simulation of the interaction between water waves and floating bodies in frequency domain.
 
@@ -70,7 +70,7 @@ This documentation is licensed under the `Creative Commons Attribution-ShareAlik
 .. |CCBYSA| image:: https://i.creativecommons.org/l/by-sa/4.0/80x15.png
 .. _`Creative Commons Attribution-ShareAlike 4.0 International License`: http://creativecommons.org/licenses/by-sa/4.0/
 
-Capytaine is a fork of Nemoh_, which has been developed by Gérard Delhommeau, Aurélien Babarit et al., (École Centrale de Nantes) and is distributed under the Apache License 2.0.
+Capytaine is a fork of the version 2 of Nemoh_, which has been developed by Gérard Delhommeau, Aurélien Babarit et al., (École Centrale de Nantes) and was distributed under the Apache License 2.0.
 
 Capytaine includes code from meshmagick_ by François Rongère (École Centrale de Nantes), licensed under the GNU General Public License (GPL).
 

diff --git a/docs/user_manual/cookbook.rst b/docs/user_manual/cookbook.rst
@@ -3,9 +3,7 @@ Cookbook
 ========
 
 This page contains several examples of Capytaine's features.
-The scripts can be downloaded individually as Python files from
-`this folder <https://github.com/capytaine/capytaine/tree/master/docs/user_manual/examples>`_
-of the Github repository.
+The scripts can be downloaded individually as Python files from the |examples_folder|_.
 
 .. contents:: Content
 

diff --git a/docs/user_manual/outputs.rst b/docs/user_manual/outputs.rst
@@ -100,6 +100,7 @@ As a workaround, the complex-valued array can be saved as a bigger real-valued a
 
 The dataset can then be reloaded by::
 
+    import xarray as xr
     from capytaine.io.xarray import merge_complex_values
     dataset = merge_complex_values(xr.open_dataset("path/to/dataset.nc"))
 
@@ -115,9 +116,11 @@ It leads to the error :code:`ValueError: unsupported dtype for netCDF4 variable:
 
 This can be fixed by explicitly converting the strings to the right format when exporting the dataset::
 
-    dataset.to_netcdf("dataset.nc",
-                      encoding={'radiating_dof': {'dtype': 'U'},
-                                'influenced_dof': {'dtype': 'U'}})
+    separate_complex_values(dataset).to_netcdf(
+      "dataset.nc",
+      encoding={'radiating_dof': {'dtype': 'U'},
+                'influenced_dof': {'dtype': 'U'}}
+    )
 
 See also `this Github issue <https://github.com/capytaine/capytaine/issues/2>`_.