Update update_readme.yml and other fixes (#2)

* use pdoc to make docstring markdown for readme
also use black for formatting
* fix github workflows to use uv
* fix uv build

.github/workflows/testing.yml

@@ -1,4 +1,4 @@
-name: CI
+name: Testing
 
 on: [push, pull_request]
 
@@ -13,17 +13,20 @@ jobs:
     - name: Set up Python
       uses: actions/setup-python@v2
       with:
-        python-version: '3.x'  # Specify the Python version you want to use
+        python-version: '3.x'
 
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: "Set up Python"
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: "pyproject.toml"
+
+    - name: Install the project
+      run: uv sync --all-extras --dev
 
     - name: Run tests
       run: |
-        python -m unittest discover -s . -p "test_*.py"
+        uv run python -m unittest discover -s tests -p "test_*.py"
 
-    - name: Run doctests
-      run: |
-        python -m doctest utils.py

.github/workflows/update_readme.yml

@@ -21,21 +21,39 @@ jobs:
       with:
         python-version: '3.x'
 
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install .
+    - name: Install uv
+      uses: astral-sh/setup-uv@v4
+
+    - name: "Set up Python"
+      uses: actions/setup-python@v5
+      with:
+        python-version-file: "pyproject.toml"
+
+    - name: Install the project
+      run: uv sync --all-extras --dev
 
     - name: Update README
       run: |
-        python update_readme.py
+        uv run docs/update_readme.py
+
+
+    - name: Check for changes
+      id: check_changes
+      run: |
+        if git diff --exit-code README.md > /dev/null; then
+          echo "no_changes=true" >> $GITHUB_ENV
+        else
+          echo "no_changes=false" >> $GITHUB_ENV
+        fi
 
     - name: Commit and push changes
+      if: env.no_changes == 'false'
       run: |
         git config --global user.name 'github-actions[bot]'
         git config --global user.email 'github-actions[bot]@users.noreply.github.com'
         git add README.md
         git commit -m "Update README.md with function docstrings"
         git push
       env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+

README.md

@@ -38,8 +38,8 @@ fig = plot_hipp_surf(label_gii.format(density=density), hemi=None, density=densi
 fig = plot_hipp_surf(label_gii.format(density=density), hemi=None, density=density, view='ventral')
 
 ```
-![png](doc/example1_0.png)
-![png](doc/example1_1.png)
+![png](docs/example1_0.png)
+![png](docs/example1_1.png)
 
 ### Example 2: Plot Left and Right Hemispheres Separately
 
@@ -59,8 +59,8 @@ fig = plot_hipp_surf(label_gii.format(density=density), hemi='right', density=de
 
 ```
 
-![png](doc/example2_0.png)
-![png](doc/example2_1.png)
+![png](docs/example2_0.png)
+![png](docs/example2_1.png)
 
 ### Example 3: Plot unfolded and canonical space separately
 
@@ -79,37 +79,67 @@ fig = plot_hipp_surf(label_gii.format(density=density), space='unfold', density=
 fig = plot_hipp_surf(label_gii.format(density=density), space='canonical', density=density, view='dorsal')
 ```
 
-![png](doc/example3_0.png)
-![png](doc/example3_1.png)
+![png](docs/example3_0.png)
+![png](docs/example3_1.png)
 
 ## 🛠️ Functions
 
 ### `plot_hipp_surf`
 
-```python
-def plot_hipp_surf(surf_map: Union[str, list], 
-                   density: str = '0p5mm', 
-                   hemi: str = 'left', 
-                   space: Optional[str] = None, 
-                   figsize: Tuple[int, int] = (12, 8), 
-                   dpi: int = 300, 
-                   vmin: Optional[float] = None, 
-                   vmax: Optional[float] = None, 
-                   colorbar: bool = False, 
-                   colorbar_shrink: float = 0.25, 
-                   cmap: Optional[Union[str, plt.cm.ScalarMappable]] = None, 
-                   view: str = 'dorsal', 
-                   avg_method: str = 'median', 
-                   bg_on_data: bool = True, 
-                   alpha: float = 0.1, 
-                   darkness: float = 2, 
-                   **kwargs) -> plt.Figure:
-    """
-    This function plots a surface map of the hippocampus, which can be a label-hippdentate shape.gii, func.gii, or a Vx1 array 
-    (where V is the number of vertices in the hippocampus and dentate). Any arguments that can be supplied to nilearn's plot_surf() 
-    can also be applied here, overriding the defaults set below.    """
-```
-
+Plot hippocampal surface map.
+
+This function plots a surface map of the hippocampus, which can be a label-hippdentate shape.gii, func.gii, or a Vx1 array
+(where V is the number of vertices in the hippocampus and dentate). Any arguments that can be supplied to nilearn's plot_surf()
+can also be applied here, overriding the defaults set below.
+
+###### Parameters
+ - **surf_map** (str or array-like):
+   The surface map to plot. This can be a file path to a .gii file or a Vx1 array.
+ - **density** (str, optional):
+   The density of the surface map. Can be 'unfoldiso', '0p5mm', '1mm', or '2mm'. Default is '0p5mm'.
+ - **hemi** (str, optional):
+   The hemisphere to plot. Can be 'left', 'right', or None (in which case both are plotted). Default is 'left'.
+ - **space** (str, optional):
+   The space of the surface map. Can be 'canonical', 'unfold', or None (in which case both are plotted). Default is None.
+ - **figsize** (tuple, optional):
+   The size of the figure. Default is (12, 8).
+ - **dpi** (int, optional):
+   The resolution of the figure in dots per inch. Default is 300.
+ - **vmin** (float, optional):
+   The minimum value for the color scale. Default is None.
+ - **vmax** (float, optional):
+   The maximum value for the color scale. Default is None.
+ - **colorbar** (bool, optional):
+   Whether to display a colorbar. Default is False.
+ - **colorbar_shrink** (float, optional):
+   The shrink factor for the colorbar. Default is 0.25.
+ - **cmap** (str or colormap, optional):
+   The colormap to use. Default is None.
+ - **view** (str, optional):
+   The view of the surface plot. Default is 'dorsal'.
+ - **avg_method** (str, optional):
+   The method to average the data. Default is 'median'.
+ - **bg_on_data** (bool, optional):
+   Whether to display the background on the data. Default is True.
+ - **alpha** (float, optional):
+   The alpha transparency level. Default is 0.1.
+ - **darkness** (float, optional):
+   The darkness level of the background. Default is 2.
+ - **axes** (matplotlib.axes.Axes or list of matplotlib.axes.Axes, optional):
+   Axes to plot on. If None, new axes will be created. If a single axis is provided, it will be used for a single plot.
+   If multiple plots are to be made, a list of axes should be provided.
+ - **figure** (matplotlib.figure.Figure, optional):
+   The figure to plot on. If None, a new figure will be created.
+ - ****kwargs** (dict):
+   Additional arguments to pass to nilearn's plot_surf().
+
+###### Returns
+ - **figure** (matplotlib.figure.Figure):
+   The figure object.
+
+###### Notes
+By default, this function will plot one hemisphere (left by default) in both canonical and unfolded space.
+Both surfaces can be plotted with hemi=None, but the same surf_map will be plotted on both.
 ## 🧪 Testing
 
 To run the tests, including unit tests and docstring tests, use the following command:

docs/update_readme.py

@@ -0,0 +1,52 @@
+import ast
+import inspect
+import os
+from pdoc.docstrings import numpy as numpy_docstring_to_markdown
+
+
+
+def get_function_docstrings(module, function_names=None):
+    """
+    Get docstrings for specific functions in a module or all functions if no names are specified.
+
+    Args:
+        module: The module object containing the functions.
+        function_names (list of str, optional): List of function names to retrieve docstrings for. 
+                                                If None, retrieves all functions.
+
+    Returns:
+        dict: A dictionary mapping function names to their docstrings.
+    """
+    # Get all functions in the module
+    functions = [obj for name, obj in inspect.getmembers(module) if inspect.isfunction(obj)]
+
+    docstrings = {}
+    for func in functions:
+        # If a list of function names is provided, filter functions
+        if function_names is None or func.__name__ in function_names:
+            docstrings[func.__name__] = numpy_docstring_to_markdown(inspect.getdoc(func))
+
+    return docstrings
+
+def update_readme(readme_path, docstrings):
+    with open(readme_path, 'r') as file:
+        lines = file.readlines()
+
+    start_functions = lines.index("## 🛠️ Functions\n")
+    end_functions = lines.index("## 🧪 Testing\n")
+
+    new_lines = lines[:start_functions + 2]
+    for func_name, docstring in docstrings.items():
+        new_lines.append(f"### `{func_name}`\n\n")
+        new_lines.append(f"{docstring}\n")
+
+    new_lines.extend(lines[end_functions:])
+
+    with open(readme_path, 'w') as file:
+        file.writelines(new_lines)
+
+if __name__ == "__main__":
+    import hippunfold_plot.plotting as plotting
+    readme_path = 'README.md'
+    docstrings = get_function_docstrings(plotting,['plot_hipp_surf'])
+    update_readme(readme_path, docstrings)