Merge pull request #245 from bird-house/packaging-fixes

Packaging fixes

.github/workflows/main.yml

@@ -52,6 +52,13 @@ jobs:
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           if [ -f requirements_dev.txt ]; then pip install -r requirements_dev.txt; fi
           if [ -f requirements_extra.txt ]; then pip install -r requirements_extra.txt; fi
+      - name: Install Birdy 🐦
+        run: |
+          python -m pip install --editable .
+      - name: Check dependencies
+        run: |
+          python -m pip list
+          python -m pip check
       - name: Build docs 🏗️
         run: |
           make docs
@@ -80,6 +87,13 @@ jobs:
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           if [ -f requirements_dev.txt ]; then pip install -r requirements_dev.txt; fi
           if [ -f requirements_extra.txt ]; then pip install -r requirements_extra.txt; fi
+      - name: Install Birdy 🐦
+        run: |
+          python -m pip install --editable .
+      - name: Check dependencies
+        run: |
+          python -m pip list
+          python -m pip check
       - name: Test with pytest ⚙️
         run: |
           make test

.gitignore

@@ -65,6 +65,7 @@ docs/make.bat
 docs/doctrees/
 docs/html/
 docs/build/
+docs/source/apidoc
 
 # External Sources
 #src/external

.pre-commit-config.yaml

@@ -6,7 +6,7 @@ repos:
     rev: v3.15.1
     hooks:
       - id: pyupgrade
-        args: ['--py39-plus']
+        args: [ '--py39-plus' ]
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
     hooks:
@@ -19,11 +19,6 @@ repos:
     hooks:
       - id: nbstripout
         files: '.ipynb'
-  - repo: https://github.com/pycqa/flake8
-    rev: 7.0.0
-    hooks:
-      - id: flake8
-        args: [ '--config=setup.cfg' ]
   - repo: https://github.com/psf/black
     rev: 24.2.0
     hooks:
@@ -34,15 +29,20 @@ repos:
     hooks:
     - id: isort
       args: [ '--profile=black' ]
+  - repo: https://github.com/pycqa/flake8
+    rev: 7.0.0
+    hooks:
+      - id: flake8
+        args: [ '--config=setup.cfg' ]
   - repo: https://github.com/nbQA-dev/nbQA
     rev: 1.8.4
     hooks:
-      - id: nbqa-black
-        args: [ '--target-version=py37' ]
-        additional_dependencies: [ 'black==24.2.0' ]
       - id: nbqa-pyupgrade
-        args: [ '--py37-plus' ]
+        args: [ '--py39-plus' ]
         additional_dependencies: [ 'pyupgrade==v3.15.1' ]
+      - id: nbqa-black
+        args: [ '--target-version=py39' ]
+        additional_dependencies: [ 'black==24.2.0' ]
       - id: nbqa-isort
         args: [ '--profile=black' ]
         additional_dependencies: [ 'isort==5.13.2' ]

.readthedocs.yml

@@ -6,15 +6,18 @@
 version: 2
 
 sphinx:
-    configuration: docs/source/conf.py
+  configuration: docs/source/conf.py
 
 build:
   os: ubuntu-22.04
   tools:
     python: "mambaforge-22.9"
+  jobs:
+    pre_build:
+      - sphinx-apidoc -o docs/source/apidoc/ --private --module-first --separate birdy
 
 # Optionally build your docs in additional formats such as PDF and ePub
 formats: all
 
 conda:
-    environment: environment-docs.yml
+  environment: environment-docs.yml

CHANGES.rst

@@ -1,6 +1,21 @@
 Change History
 **************
 
+v0.8.6 (2024-xx-xx)
+===================
+
+Changes:
+
+* Restructure the package so that the wheel does not install the testing and docs as non-importable packages.
+* Ensure that data required to run tests and build docs is present in the source distribution (via `Manifest.in` changes).
+* Documentation now includes a `sphinx-apidoc`-based listing of all installed modules and functions
+* Add `sphinx-copybutton` and `sphinx-codeautolink` in order to increase the usefulness of code-blocks in the example documentation (copying of code blocks and ability to click on `birdy` objects and go straight to the documentation entry for the object).
+* All documentation build warnings have been addressed.
+* Add the `birdy[extra]` pip install recipe to be able to install all extras needed more directly.
+* Raise the minimum Python required to 3.9 in the setup block.
+* Remove the Python package for `pandoc` (unmaintained).
+* Add a documentation entry on using `build` to build the documentation.
+
 0.8.5 (2024-03-14)
 ==================
 

MANIFEST.in

@@ -1,9 +1,18 @@
-include *.rst
 graft birdy
-global-exclude __pycache__
-global-exclude *.py[co]
 
+include *.rst
 include LICENSE.txt
 include requirements.txt
 include requirements_dev.txt
 include requirements_extra.txt
+include setup.cfg
+include docs Makefile make.bat
+
+recursive-include docs/source Makefile make.bat *.rst *.py *.ipynb *.svg *.ico *.txt *.yml *.cfg *.md
+recursive-include tests *.py *.nc *.tif *.geojson *.xml
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+recursive-exclude * *.ipynb_checkpoints
+recursive-exclude docs/build *
+recursive-exclude docs/source/apidoc *.rst

Makefile

@@ -38,6 +38,11 @@ clean-build: ## remove build artifacts
 	find . -name '*.egg-info' -exec rm -fr {} +
 	find . -name '*.egg' -exec rm -f {} +
 
+clean-docs: ## remove docs artifacts
+	rm -f docs/source/apidoc/birdy*.rst
+	rm -f docs/source/apidoc/modules.rst
+	$(MAKE) -C docs clean
+
 clean-pyc: ## remove Python file artifacts
 	find . -name '*.pyc' -exec rm -f {} +
 	find . -name '*.pyo' -exec rm -f {} +
@@ -72,8 +77,11 @@ coverage: ## check code coverage quickly with the default Python
 	coverage html
 	$(BROWSER) htmlcov/index.html
 
-docs: ## generate Sphinx HTML documentation, including API docs
-	$(MAKE) -C docs clean
+autodoc: clean-docs ## create sphinx-apidoc files
+	mkdir -p docs/source/apidoc/
+	sphinx-apidoc -o docs/source/apidoc/ --private --module-first --separate birdy
+
+docs: autodoc ## generate Sphinx HTML documentation, including API docs
 	$(MAKE) -C docs html
 
 servedocs: docs ## compile the docs watching for changes

birdy/cli/__init__.py

@@ -1,4 +1,8 @@
+# noqa: D205, D400
 """
+Birdy CLI module
+================
+
 Birdy has a command line interface to interact with a Web Processing Service.
 
 Example

birdy/client/__init__.py

@@ -1,29 +1,25 @@
-"""WPSClient Class.
+# noqa: D205, D400
+"""
+WPSClient Class
+===============
 
-The :class:`WPSClient` class aims to make working with WPS servers easy,
-even without any prior knowledge of WPS.
+The :class:`WPSClient` class aims to make working with WPS servers easy, even without any prior knowledge of WPS.
 
-Calling the :class:`WPSClient` class creates an instance whose methods call
-WPS processes. These methods are generated at runtime based on the
-process description provided by the WPS server. Calling a function sends
-an `execute` request to the server. The server response is parsed and
-returned as a :class:`WPSExecution` instance, which includes information
-about the job status, the progress percentage, the starting time, etc. The
-actual output from the process are obtained by calling the `get` method.
+Calling the :class:`WPSClient` class creates an instance whose methods call WPS processes.
+These methods are generated at runtime based on the process description provided by the WPS server.
+Calling a function sends an `execute` request to the server. The server response is parsed and
+returned as a :class:`WPSExecution` instance, which includes information about the job status, the progress percentage,
+the starting time, etc. The actual output from the process are obtained by calling the `get` method.
 
 The output is parsed to convert the outputs in native Python whenever possible.
-`LiteralOutput` objects (string, float, integer, boolean) are automatically
-converted to their native format. For `ComplexOutput`, the module can either
-return a link to the output files stored on the server, or try to
-convert the outputs to a Python object based on their mime type. This conversion
-will occur with `get(asobj=True)`. So for example, if the mime type is
-'application/json', the output would be a `dict`.
-
-Inputs to processes can be native Python types (string, float, int, date, datetime),
-http links or local files. Local files can be transferred to a remote server by
-including their content into the WPS request. Simply set the input to a valid path
-or file object and the client will take care of reading and converting the file.
+`LiteralOutput` objects (string, float, integer, boolean) are automatically converted to their native format.
+For `ComplexOutput`, the module can either return a link to the output files stored on the server,
+or try to convert the outputs to a Python object based on their mime type. This conversion will occur with
+`get(asobj=True)`. So for example, if the mime type is 'application/json', the output would be a `dict`.
 
+Inputs to processes can be native Python types (string, float, int, date, datetime), http links or local files.
+Local files can be transferred to a remote server by including their content into the WPS request.
+Simply set the input to a valid path or file object and the client will take care of reading and converting the file.
 
 Example
 -------
@@ -55,10 +51,8 @@
 
 Authentication
 --------------
-If you want to connect to a server that requires authentication, the
-:class:`WPSClient` class accepts an `auth` argument that
-behaves exactly like in the popular `requests` module
-(see `requests Authentication`_)
+If you want to connect to a server that requires authentication, the :class:`WPSClient` class accepts
+an `auth` argument that behaves exactly like in the popular `requests` module (see `requests Authentication`_)
 
 The simplest form of authentication is HTTP Basic Auth. Although
 wps processes are not commonly protected by this authentication method,
@@ -69,11 +63,10 @@
     >>> auth = HTTPBasicAuth('user', 'pass')
     >>> wps = WPSClient('http://www.example.com/wps', auth=auth)
 
-Because any `requests`-compatible class is accepted, custom
-authentication methods are implemented the same way as in `requests`.
+Because any `requests`-compatible class is accepted, custom authentication methods are implemented
+the same way as in `requests`.
 
-For example, to connect to a magpie_ protected wps, you can use the
-requests-magpie_ module::
+For example, to connect to a magpie_ protected wps, you can use the requests-magpie_ module::
 
     >>> from birdy import WPSClient
     >>> from requests_magpie import MagpieAuth
@@ -83,11 +76,10 @@
 Output format
 -------------
 
-Birdy automatically manages process output to reflect it's default values or
-Birdy's own defaults.
+Birdy automatically manages process output to reflect its default values or Birdy's own defaults.
 
 However, it's possible to customize the output of a process. Each process has an input
-named ``output_formats`, that takes a dictionary as a parameter::
+named ``output_formats``, that takes a dictionary as a parameter::
 
     # example format = {
     #     'output_identifier': {
@@ -122,7 +114,6 @@
 .. _requests Authentication: https://2.python-requests.org/en/master/user/authentication/
 .. _magpie: https://github.com/ouranosinc/magpie
 .. _requests-magpie: https://github.com/ouranosinc/requests-magpie
-
 """
 
 from birdy.client.notebook import gui  # noqa: F401

birdy/dependencies.py

@@ -1,9 +1,13 @@
+# noqa: D205,D400
 """
+Dependencies Module
+===================
+
 Module for managing optional dependencies.
 
 Example usage::
 
-    from birdy.dependencies import ipywidgets as widgets
+    >>> from birdy.dependencies import ipywidgets as widgets
 """
 
 import warnings

birdy/ipyleafletwfs/__init__.py

@@ -1,3 +1,32 @@
-# noqa: D104
+# noqa: D205,D400
+"""
+IpyleafletWFS Module
+====================
+
+This module facilitates the use of a WFS service through the ipyleaflet module in jupyter notebooks.
+It uses owslib to get a geojson out of a WFS service, and then creates an ipyleaflet GeoJSON layer with it.
+
+Dependencies
+------------
+
+Ipyleaflet and Ipywidgets dependencies are included in the requirements_extra.txt, at the root of this repository.
+To install::
+
+    $ pip install -r requirements_extra.txt
+
+Use
+---
+
+This module is to be used inside a jupyter notebook, either with a standard server or through vscode/pycharm.
+There are notebook examples which show how to use this module and what can be done with it.
+
+The WFS request is filtered by the extent of the visible map, to make large layers easier to work with.
+Using the on-map 'Refresh WFS layer' button will make a new request for the current extent.
+
+.. warning::
+    WFS requests and GeoJSON layers are costly operations to process and render.
+    Trying to load lake layers at the nationwide extent may take a long time and probably crash.
+    The more dense and complex the layer, the more zoomed-in the map extent should be.
+"""
 
 from .base import IpyleafletWFS  # noqa: F401

birdy/utils.py

@@ -44,12 +44,11 @@ def is_url(url):
 
 
 def is_opendap_url(url):
-    """
-    Check if a provided url is an OpenDAP url.
+    """Check if a provided url is an OpenDAP url.
 
     The DAP Standard specifies that a specific tag must be included in the
     Content-Description header of every request. This tag is one of:
-        "dods-dds" | "dods-das" | "dods-data" | "dods-error"
+    "dods-dds" | "dods-das" | "dods-data" | "dods-error"
 
     So we can check if the header starts with `dods`.
 

docs/source/api.rst

@@ -12,8 +12,10 @@ Using the command line
 ======================
 
 .. automodule:: birdy.cli
+    :noindex:
 
 Using the Python library
 ========================
 
 .. automodule:: birdy.client
+    :noindex: