Documentation

.readthedocs.yaml

@@ -0,0 +1,32 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "19"
+    # rust: "1.64"
+    # golang: "1.19"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#    - pdf
+#    - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+# python:
+#    install:
+#    - requirements: docs/requirements.txt

README.md

@@ -31,18 +31,23 @@ We encourage usage and welcome feature requests.
 It is appreciated if visible credit is given by any projects using `archeryutils`.
 
 ### Installation
-To install clone the repository, navigate to `/archeryutils`, and run:
+To install the library via pip for use in a project you can run:
 
-    python3 -m pip install .
+    python -m pip install git+https://github.com/jatkinson1000/archeryutils.git
 
 It is recommended to use a virtual environment.
 
 There are plans to host the library on PyPI in due course.
 
+If you want a local install that you can edit instead, clone the repository,
+navigate to `/archeryutils`, and run:
+
+    python3 -m pip install .
+
 ### Getting Started
 There are examples of some of the different functionalities in the jupyter notebook
 `examples.ipynb`.
-This can be run using:
+This can be run from a local install using:
 
     pip install notebook
 

archeryutils/classifications/agb_field_classifications.py

@@ -1,17 +1,10 @@
 """
-Code for calculating Archery GB classifications.
-
-Extended Summary
-----------------
-Code to add functionality to the basic handicap equations code
-in handicap_equations.py including inverse function and display.
+Code for calculating Archery GB field classifications.
 
 Routine Listings
 ----------------
-_make_agb_field_classification_dict
 calculate_agb_field_classification
 agb_field_classification_scores
-
 """
 
 # Due to structure of similar classification schemes they may trigger duplicate code.
@@ -54,6 +47,7 @@ def _make_agb_field_classification_dict() -> Dict[str, Dict[str, Any]]:
     ----------
     ArcheryGB 2023 Rules of Shooting
     ArcheryGB Shooting Administrative Procedures - SAP7 (2023)
+
     """
     agb_field_classes = [
         "Grand Master Bowman",
@@ -199,7 +193,7 @@ def calculate_agb_field_classification(
     ----------
     roundname : str
         name of round shot as given by 'codename' in json
-    score : int
+    score : float
         numerical score on the round to calculate classification for
     bowstyle : str
         archer's bowstyle under AGB outdoor target rules
@@ -213,10 +207,28 @@ def calculate_agb_field_classification(
     classification_from_score : str
         the classification appropriate for this score
 
+    Raises
+    ------
+    ValueError
+        If an invalid score for the requested round is provided
+
     References
     ----------
     ArcheryGB 2023 Rules of Shooting
     ArcheryGB Shooting Administrative Procedures - SAP7 (2023)
+
+    Examples
+    --------
+    >>> from archeryutils import classifications as class_func
+    >>> class_func.calculate_agb_field_classification(
+    ...     "wa_field_24_red_marked",
+    ...     247,
+    ...     "recurve",
+    ...     "male",
+    ...     "adult",
+    ... )
+    '2nd Class'
+
     """
     # Check score is valid
     if score < 0 or score > ALL_AGBFIELD_ROUNDS[roundname].max_score():
@@ -285,13 +297,25 @@ def agb_field_classification_scores(
 
     Returns
     -------
-    classification_scores : ndarray
-        abbreviation of the classification appropriate for this score
+    classification_scores : list of int
+        scores required for each classification in descending order
 
     References
     ----------
     ArcheryGB Rules of Shooting
     ArcheryGB Shooting Administrative Procedures - SAP7
+
+    Examples
+    --------
+    >>> from archeryutils import classifications as class_func
+    >>> class_func.agb_field_classification_scores(
+    ...     "wa_field_24_red_marked",
+    ...     "recurve",
+    ...     "male",
+    ...     "adult",
+    ... )
+    [338, 317, 288, 260, 231, 203]
+
     """
     # Unused roundname argument to keep consistency with other classification functions
     # pylint: disable=unused-argument

archeryutils/classifications/agb_indoor_classifications.py

@@ -3,7 +3,6 @@
 
 Routine Listings
 ----------------
-_make_agb_old_indoor_classification_dict
 calculate_agb_indoor_classification
 agb_indoor_classification_scores
 """
@@ -143,10 +142,28 @@ def calculate_agb_indoor_classification(
     classification_from_score : str
         the classification appropriate for this score
 
+    Raises
+    ------
+    ValueError
+        If an invalid score for the requested round is provided
+
     References
     ----------
     ArcheryGB 2023 Rules of Shooting
     ArcheryGB Shooting Administrative Procedures - SAP7 (2023)
+
+    Examples
+    --------
+    >>> from archeryutils import classifications as class_func
+    >>> class_func.calculate_agb_indoor_classification(
+    ...     "wa18",
+    ...     547,
+    ...     "compound",
+    ...     "male",
+    ...     "50+",
+    ... )
+    'I-B2'
+
     """
     # Check score is valid
     if score < 0 or score > ALL_INDOOR_ROUNDS[roundname].max_score():
@@ -191,7 +208,7 @@ def agb_indoor_classification_scores(
     age_group: str,
 ) -> List[int]:
     """
-    Calculate new (2023) AGB indoor classification scores for category.
+    Calculate 2023 AGB indoor classification scores for category.
 
     Subroutine to calculate classification scores for a specific category and round.
     Appropriate ArcheryGB age groups and classifications.
@@ -210,12 +227,34 @@ def agb_indoor_classification_scores(
     Returns
     -------
     classification_scores : ndarray
-        scores required for each classification band
+        scores required for each classification in descending order
 
     References
     ----------
     ArcheryGB Rules of Shooting
     ArcheryGB Shooting Administrative Procedures - SAP7
+
+    Examples
+    --------
+    >>> from archeryutils import classifications as class_func
+    >>> class_func.agb_indoor_classification_scores(
+    ...     "portsmouth",
+    ...     "barebow",
+    ...     "male",
+    ...     "under 12",
+    ... )
+    [411, 360, 301, 240, 183, 134, 95, 66]
+
+    If a classification cannot be achieved a fill value of `-9999` is returned:
+
+    >>> class_func.agb_indoor_classification_scores(
+    ...     "worcester",
+    ...     "compound",
+    ...     "female",
+    ...     "adult",
+    ... )
+    [-9999, -9999, 298, 289, 276, 257, 233, 200]
+
     """
     # deal with reduced categories:
     if bowstyle.lower() in ("flatbow", "traditional", "asiatic"):

archeryutils/classifications/agb_old_indoor_classifications.py

@@ -1,9 +1,8 @@
 """
-Code for calculating old Archery GB indoor classifications.
+Code for calculating old (pre-2023) Archery GB indoor classifications.
 
 Routine Listings
 ----------------
-_make_AGB_old_indoor_classification_dict
 calculate_AGB_old_indoor_classification
 AGB_old_indoor_classification_scores
 """
@@ -113,8 +112,21 @@ def calculate_agb_old_indoor_classification(
 
     References
     ----------
-    ArcheryGB 2023 Rules of Shooting
-    ArcheryGB Shooting Administrative Procedures - SAP7 (2023)
+    ArcheryGB Rules of Shooting
+    ArcheryGB Shooting Administrative Procedures - SAP7 (pre-2023)
+
+    Examples
+    --------
+    >>> from archeryutils import classifications as class_func
+    >>> class_func.calculate_agb_old_indoor_classification(
+    ...     "wa18",
+    ...     547,
+    ...     "compound",
+    ...     "male",
+    ...     "adult",
+    ... )
+    'C'
+
     """
     # Check score is valid
     if score < 0 or score > ALL_INDOOR_ROUNDS[roundname].max_score():
@@ -179,12 +191,35 @@ def agb_old_indoor_classification_scores(
     Returns
     -------
     classification_scores : ndarray
-        abbreviation of the classification appropriate for this score
+        scores required for each classification in descending order
 
     References
     ----------
     ArcheryGB Rules of Shooting
     ArcheryGB Shooting Administrative Procedures - SAP7
+
+    Examples
+    --------
+    >>> from archeryutils import classifications as class_func
+    >>> class_func.agb_old_indoor_classification_scores(
+    ...     "portsmouth",
+    ...     "barebow",
+    ...     "male",
+    ...     "under 12",
+    ... )
+    [592, 582, 554, 505, 432, 315, 195, 139]
+
+    If a classification cannot be achieved a fill value of `-9999` is returned:
+
+    >>> class_func.agb_old_indoor_classification_scores(
+    ...     "worcester",
+    ...     "compound",
+    ...     "female",
+    ...     "adult",
+    ... )
+    [299, 296, 279, 247, 200, 132, 65, 49]
+
+
     """
     # enforce compound scoring
     if bowstyle.lower() in ("compound"):