docs: copy button (#255)

* update docs

* lint

* Add sphinx-copybutton to requirements.txt

* Don't copy prompts characters

---------

Co-authored-by: Philippe Miron <[email protected]>
Co-authored-by: milancurcic <[email protected]>

Author: 3 people

clouddrift/analysis.py

@@ -159,11 +159,13 @@ def chunk(
            [3, 4]])
 
     To discard the starting elements of the array instead, use ``align="end"``:
+
     >>> chunk([1, 2, 3, 4, 5], 2, align="end")
     array([[2, 3],
            [4, 5]])
 
     To center the chunks by discarding both ends of the array, use ``align="middle"``:
+
     >>> chunk([1, 2, 3, 4, 5, 6, 7, 8], 3, align="middle")
     array([[2, 3, 4],
            [5, 6, 7]])
@@ -350,6 +352,7 @@ def ragged_to_regular(
            [ 4.,  5.]])
 
     You can specify an alternative fill value:
+
     >>> ragged_to_regular(np.array([1, 2, 3, 4, 5]), np.array([2, 1, 2]), fill_value=999)
     array([[ 1.,    2.],
            [ 3., -999.],

clouddrift/sphere.py

@@ -518,7 +518,7 @@ def cartesian_to_spherical(
     the point lon = 0, lat = 0. This function is inverted by `spherical_to_cartesian`.
 
     Parameters
-    -------
+    ----------
     x : np.ndarray
         x-coordinates in 3D.
     y : np.ndarray
@@ -527,7 +527,7 @@ def cartesian_to_spherical(
         z-coordinates in 3D.
 
     Returns
-    ----------
+    -------
     lon : np.ndarray
         An N-d array of longitudes in degrees in range [-180, 180].
     lat : np.ndarray

docs/conf.py

@@ -35,6 +35,7 @@
     "sphinx.ext.autosummary",
     "sphinx.ext.doctest",
     "sphinx.ext.inheritance_diagram",
+    "sphinx_copybutton",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -63,3 +64,6 @@
         "image_dark": "logo.png",
     }
 }
+
+# sphinx-copybutton settings
+copybutton_exclude = ".linenos, .gp"  # don't copy prompts or line numbers

docs/contributing.rst

@@ -25,7 +25,8 @@ We also welcome contributions to improving the documentation of the project. To
 .. code-block:: console
 
   conda install sphinx
-  pip install pydata-sphinx-theme
+  pip install sphinx_book_theme
+  pip install sphinx-copybutton
 
 Then, from the ``clouddrift/docs`` directory, run
 

docs/requirements.txt

@@ -1,2 +1,3 @@
 sphinx
 sphinx-book-theme
+sphinx-copybutton