API reference

[VeckoTheGecko]

This PR:

• adds an API page
• bugfixes link resolving function
• adds version dunder methods

Happy to discuss and edit layout as required. @michaeldenes could you review the generated docs and see it's as you expect? The docs are using the numpy docstring format but I'm not sure if all the docstrings adhere to that. I can install tooling to help lint that.

This closes #46

[erikvansebille]

Hmm, getting an error when I try this code:

(parcels) erik ~/Codes/PlasticParcels/docs % make html  
Running Sphinx v7.3.7

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/Users/erik/anaconda3/envs/parcels/lib/python3.12/site-packages/sphinx/config.py", line 509, in eval_config_file
    exec(code, namespace)  # NoQA: S102
    ^^^^^^^^^^^^^^^^^^^^^
  File "/Users/erik/Codes/PlasticParcels/docs/conf.py", line 17, in <module>
    import plasticparcels
  File "/Users/erik/Codes/PlasticParcels/plasticparcels/__init__.py", line 5, in <module>
    from plasticparcels._version_setup import __version__, __version_tuple__  # noqa
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'plasticparcels._version_setup'

I did just run

(parcels) erik ~/Codes/PlasticParcels % pip install --no-build-isolation --no-deps -e .
Obtaining file:///Users/erik/Codes/PlasticParcels
  Checking if build backend supports build_editable ... done
  Preparing editable metadata (pyproject.toml) ... done
Building wheels for collected packages: plasticparcels
  Building editable for plasticparcels (pyproject.toml) ... done
  Created wheel for plasticparcels: filename=plasticparcels-0.0.0-0.editable-py3-none-any.whl size=5240 sha256=29281eedc8f7c6cbe06fe1372c1a59c4c95816fb6387a56911470499e3ae0af4
  Stored in directory: /private/var/folders/x0/1qxj679n55zcybylvdsb4bxh0000gq/T/pip-ephem-wheel-cache-hbca0z3n/wheels/46/7e/4c/6794e9b66cc3c539fe45e909a81eb509c8f932f180a62bb0a9
Successfully built plasticparcels
Installing collected packages: plasticparcels
Successfully installed plasticparcels-0.0.0

But that didn't help...

[VeckoTheGecko]

@erikvansebille I tried to recreate your error, but I couldn't. Perhaps its something to do with your conda environment? (e.g., having parcels installed as a dev dependency?)

conda env create -n pp2 -f docs/environment_docs.yml
pip install --no-build-isolation --no-deps -e .
cd docs
make html

[erikvansebille]

Hmm, still doesn't work. See below

(parcels) erik ~/Codes/PlasticParcels % conda env create -n plasticparcels -f docs/environment_docs.yml
Channels:
 - conda-forge
 - defaults
Platform: osx-64
Collecting package metadata (repodata.json): done
Solving environment: done

Downloading and Extracting Packages:
                                                                                                                                                                           
Preparing transaction: done                                                                                                                                                
Verifying transaction: done                                                                                                                                                
Executing transaction: done                                                                                                                                                
#                                                                                                                                                                          
# To activate this environment, use                                                                                                                                        
#                                                                                                                                                                          
#     $ conda activate plasticparcels                                                                                                                                      
#                                                                                                                                                                          
# To deactivate an active environment, use                                                                                                                                 
#                                                                                                                                                                          
#     $ conda deactivate                                                                                                                                                   
                                                                                                                                                                           
(parcels) erik ~/Codes/PlasticParcels % conda activate plasticparcels
(plasticparcels) erik ~/Codes/PlasticParcels % pip install --no-build-isolation --no-deps -e .
Obtaining file:///Users/erik/Codes/PlasticParcels
  Checking if build backend supports build_editable ... done
  Preparing editable metadata (pyproject.toml) ... done
Building wheels for collected packages: plasticparcels
  Building editable for plasticparcels (pyproject.toml) ... done
  Created wheel for plasticparcels: filename=plasticparcels-0.0.0-0.editable-py3-none-any.whl size=5238 sha256=3dfd01c2a1a18b0658739405d0d0bac82eb2780958d9bc91de5df9b62690a8fb
  Stored in directory: /private/var/folders/x0/1qxj679n55zcybylvdsb4bxh0000gq/T/pip-ephem-wheel-cache-yv031jol/wheels/46/7e/4c/6794e9b66cc3c539fe45e909a81eb509c8f932f180a62bb0a9
Successfully built plasticparcels
Installing collected packages: plasticparcels
Successfully installed plasticparcels-0.0.0
(plasticparcels) erik ~/Codes/PlasticParcels % cd docs
(plasticparcels) erik ~/Codes/PlasticParcels/docs % make html
Running Sphinx v5.3.0

Configuration error:
There is a programmable error in your configuration file:

Traceback (most recent call last):
  File "/Users/erik/anaconda3/envs/plasticparcels/lib/python3.12/site-packages/sphinx/config.py", line 350, in eval_config_file
    exec(code, namespace)
  File "/Users/erik/Codes/PlasticParcels/docs/conf.py", line 17, in <module>
    import plasticparcels
  File "/Users/erik/Codes/PlasticParcels/plasticparcels/__init__.py", line 5, in <module>
    from plasticparcels._version_setup import __version__, __version_tuple__  # noqa
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
ModuleNotFoundError: No module named 'plasticparcels._version_setup'

make: *** [html] Error 2
(plasticparcels) erik ~/Codes/PlasticParcels/docs % 

[VeckoTheGecko]

If you're encountering this error, its likely your install isn't behaving. Can you import plasticparcels if you open a Python prompt?

[VeckoTheGecko]

I have installed Ruff for this project and removed the previous tooling (flake8, isort). @michaeldenes this includes tooling to check your docstring format against pydocstyle (D) and pydoclint (DOC) rules. To use this tooling and see the errors you can do:

conda install pre_commit
pre-commit run --all-files

With the updated pyproject.toml config, your Ruff extension should pick up the errors and display them in VScode. If you instead want to disable the docstring checks do:

[tool.ruff.lint]
select = [
    "E",  # Error
    "F",  # pyflakes
    # "I",  # isort
    "B",  # Bugbear
    # "UP", # pyupgrade
    "LOG", # logging
    "ICN", # import conventions
    "G", # logging-format
    "RUF", # ruff
-   "D",  # pydocstyle
-   "DOC", # pydoclint
]

in pyproject.toml

If you want to enable isort, uncomment the code above in the select list.

[VeckoTheGecko]

I have also tried adding pre-commit in CI. The owner of this repo should get a GitHub notification asking to authorise access.

[michaeldenes]

@VeckoTheGecko this is looking good now. One nice to have would be a section navigation, like the parcels api reference, that allows the user to see 'constructors', 'kernels', etc.

EDIT: I think also, if anything under 'scripts' can be ignored (also for the linting/ruff stuff), if that's possible?

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 35.71429% with 9 lines in your changes missing coverage. Please review.

Project coverage is 66.85%. Comparing base (d4ed9ae) to head (7e419d3).

Files	Patch %	Lines
plasticparcels/kernels.py	0.00%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #47      +/-   ##
==========================================
+ Coverage   66.71%   66.85%   +0.13%     
==========================================
  Files           8        8              
  Lines         712      715       +3     
==========================================
+ Hits          475      478       +3     
  Misses        237      237              

Flag	Coverage Δ
unit-tests	66.85% <35.71%> (+0.13%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.