complete docstrings for yfpy

cuddebtj · May 6, 2022 · 2fc32a0 · 2fc32a0
1 parent caa93b1
commit 2fc32a0
Show file tree

Hide file tree

Showing 10 changed files with 561 additions and 416 deletions.
diff --git a/DEPLOYMENT.md b/DEPLOYMENT.md
@@ -3,16 +3,16 @@
 1. (Optional) Clear virtual machine of old requirements:
 
     ```shell
-    pip uninstall -y -r <(pip freeze)    
+    pip uninstall -y -r <(pip freeze)
     ```
 
 2. (Optional) Check `requirements.txt` and `requirement-dev.txt` for latest dependency versions.
 
-3. Update virtual machine with the latest dependencies:
+3. (Optional) Update virtual machine with the latest dependencies:
 
     ```shell
-    pip install -r requirements.txt    
-    pip install -r requirements-dev.txt    
+    pip install -r requirements.txt
+    pip install -r requirements-dev.txt
     ```
 
 4. Lint code with `flake8`:
@@ -42,13 +42,13 @@
 8. Run `pytest` unit tests:
 
     ```shell
-    python -m pytest -v -s -m unit 
+    python -m pytest -v -s -m unit
     ```
 
 9. Run `pytest` integration tests:
 
     ```shell
-    python -m pytest -v -s -m integration 
+    python -m pytest -v -s -m integration
     ```
 
 10. (Optional) Run all tests from `pytest` file:
@@ -73,13 +73,13 @@
 13. Check Sphinx documentation locally:
 
      ```shell
-     open build/html/index.html    
+     open build/html/index.html
      ```
 
 14. Navigate to root directory:
 
      ```shell
-     cd ..    
+     cd ..
      ```
 
 15. Execute `git add .`, `git commit -m 'commit message'`, and `git push`.
@@ -89,8 +89,8 @@
      `git tag -a [tag_name/version] -m [message]`
 
      ```shell
-     git tag -a v1.0.0 -m 'first release'    
-     git push origin --tags    
+     git tag -a v1.0.0 -m 'first release'
+     git push origin --tags
      ```
 
 17. Build the package (will also auto-update the version based on teh above git tag):

diff --git a/README.md b/README.md
@@ -21,19 +21,24 @@
 
 ---
 
-#### Do you like the YFPY API wrapper? Star the repository here on GitHub and please consider helping support its ongoing development:
+<sub>***Do you like the YFPY API wrapper? Star the repository on GitHub and please consider helping support its ongoing development:***</sub>
 
-[<img src="https://github.com/uberfastman/yfpy/raw/develop/resources/images/donate-paypal.png" width="100"/>](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=VZZCNLRHH9BQS) [<img src="https://github.com/uberfastman/yfpy/raw/develop/resources/images/donate-bitcoin.png" width="100"/>](https://share.trustwallet.com/ZoAkTpY1I9) [<img src="https://github.com/uberfastman/yfpy/raw/develop/resources/images/donate-ethereum.png" width="100"/>](https://share.trustwallet.com/MF8YBO01I9)
+[<img src="https://github.com/uberfastman/yfpy/raw/develop/resources/images/donate-paypal.png" width="75"/>](https://www.paypal.com/cgi-bin/webscr?cmd=_donations&business=VZZCNLRHH9BQS) [<img src="https://github.com/uberfastman/yfpy/raw/develop/resources/images/donate-bitcoin.png" width="75"/>](https://share.trustwallet.com/ZoAkTpY1I9) [<img src="https://github.com/uberfastman/yfpy/raw/develop/resources/images/donate-ethereum.png" width="75"/>](https://share.trustwallet.com/MF8YBO01I9)
 
-| Cryptocurrency |                   Address                    |
-|---------------:|:--------------------------------------------:|
-|  Bitcoin (BTC) | `bc1qataspvklhewtswm357m0677q4raag5new2xt3e` | 
-| Ethereum (ETH) | `0x5eAa522e66a90577D49e9E72f253EC952CDB4059` |
+|                                                                <sub><sup>Cryptocurrency</sup></sub> |                                                      <sub><sup>Address</sup></sub>                                                       |
+|----------------------------------------------------------------------------------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------:|
+|                                                                 <sub><sup>Bitcoin (BTC)</sup></sub> |                                    <sub><sup>`bc1qataspvklhewtswm357m0677q4raag5new2xt3e`</sup></sub>                                    | 
+|                                                                <sub><sup>Ethereum (ETH)</sup></sub> |                                    <sub><sup>`0x5eAa522e66a90577D49e9E72f253EC952CDB4059`</sup></sub>                                    |
+
+<sub><sup></sup></sub>
 
 ---
 
 ## Yahoo Fantasy Sports API Wrapper (YFPY)
 
+### [READ THE DOCS HERE!](https://yfpy.uberfastman.com)
+<sup>Detailed documentation on YFPY can be found at [https://yfpy.uberfastman.com](https://yfpy.uberfastman.com).</sup>
+
 ### Table of Contents
 * [About](#about)
 * [Installation](#installation)
@@ -81,7 +86,7 @@ YFPY is a comprehensive wrapper around the Yahoo Fantasy Sports API. It allows f
     * `API Permissions` (**Required**): check the `Fantasy Sports` checkbox. You can leave the `Read` option selected (appears in an accordion expansion underneath the `Fantasy Sports` checkbox once you select it).
     * Click the `Create App` button.
     * Once the app is created, it should redirect you to a page for your app, which will show both a `Client ID` and a `Client Secret`.
-    * Make a copy of [`test/integration/EXAMPLE.private.json`](test/integration/EXAMPLE.private.json), rename it to just `private.json`, and copy the `Client ID` and `Client Secret` values to their respective fields (make sure the strings are wrapped regular quotes (`""`), NOT formatted quotes (`“”`)). The path to this file will be needed to point YFPY to your credentials.
+    * Make a copy of [`test/integration/EXAMPLE.private.json`](https://github.com/uberfastman/yfpy/blob/develop/test/integration/EXAMPLE.private.json), rename it to just `private.json`, and copy the `Client ID` and `Client Secret` values to their respective fields (make sure the strings are wrapped regular quotes (`""`), NOT formatted quotes (`“”`)). The path to this file will be needed to point YFPY to your credentials.
     * Now you should be ready to initialize the OAuth2 connection between YFPY your Yahoo account.
 
 ---
@@ -100,16 +105,16 @@ YFPY is a comprehensive wrapper around the Yahoo Fantasy Sports API. It allows f
 
 YFPY has a collection of fully functional code snippets that can be run using [pytest](https://docs.pytest.org/en/6.2.x/). These snippets demonstrate how to use YFPY to retrieve your Yahoo Fantasy Sports data.
 
-* See the [`test/integration`](test/integration) directory for the example code snippets.
-* Before running any tests, make a copy of [`test/integration/EXAMPLE.env`](test/integration/EXAMPLE.env) in the [`test/integration`](test/integration) directory and rename it to `.env`.
+* See the [`test/integration`](https://github.com/uberfastman/yfpy/blob/develop/test/integration/) directory for the example code snippets.
+* Before running any tests, make a copy of [`test/integration/EXAMPLE.env`](https://github.com/uberfastman/yfpy/blob/develop/test/integration/EXAMPLE.env) in the [`test/integration`](https://github.com/uberfastman/yfpy/blob/develop/test/integration/) directory and rename it to `.env`.
 * Copy your Yahoo `Client ID` and `Client Secret` into the environment variables in `.env` so that pytest can use them when hitting the Yahoo Fantasy Sports API.
 * If this is the first time running pytest with your Yahoo API credentials, you ***MUST*** allow interactive prompts within pytest by using the `-s` flag.
 * You can invoke all pytest tests (both integration test and unit tests) by running the below from the root directory:
   * `pytest -v -s`
-* If you want to run only the integration tests, you can run:
-  * `pytest -v -s -m integration`
 * If you want to run only the unit tests, you can run:
   * `pytest -v -s -m unit`
+* If you want to run only the integration tests, you can run:
+  * `pytest -v -s -m integration`
 
 ---
 

diff --git a/docs-sphinx/source/_static/custom.css b/docs-sphinx/source/_static/custom.css
@@ -0,0 +1,8 @@
+
+span.sig-name.descname {
+    color: mediumblue !important;
+}
+
+html[data-theme='dark'] .theme-switcher {
+    box-shadow: 0 3px 14px 4px rgba(255, 255, 255, 0.62) !important;
+}
diff --git a/docs-sphinx/source/conf.py b/docs-sphinx/source/conf.py
@@ -31,26 +31,29 @@
 copyright = f"{date.today().year}, Wren J. R. (uberfastman)"
 author = "Wren J. R. (uberfastman)"
 
-# The full version, including alpha/beta/rc tags
+# The short X.Y version.
+version = __version__
+# The full version, including alpha/beta/rc tags.
 release = __version__
 
 # -- General configuration ---------------------------------------------------
 
 # Add any Sphinx extension module names here, as strings. They can be
-# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# extensions coming with Sphinx (named "sphinx.ext.*") or your custom
 # ones.
 extensions = [
     "sphinx.ext.autodoc",  # autogenerate documentation from docstrings
     "sphinx.ext.napoleon",  # support google style docstrings
     "sphinx.ext.autosummary",  # recursively generate documentation from dynamic nested modules
-    'sphinx.ext.intersphinx',  # link to external documentation (must also use sphinx generated docs: .inv file)
-    'sphinx.ext.viewcode',  # add links to the Python source code for classes, functions etc.
-    'sphinx_autodoc_typehints',  # automatically document param types (less noise in class signature)
+    "sphinx.ext.intersphinx",  # link to external documentation (must also use sphinx generated docs: .inv file)
+    "sphinx.ext.viewcode",  # add links to the Python source code for classes, functions etc.
+    "sphinx_autodoc_typehints",  # automatically document param types (less noise in class signature)
+    "sphinx_rtd_dark_mode",  # add toggleable dark mode to sphinx ReadTheDocs theme
     "myst_parser"  # markdown parsing
 ]
 
 # Add any paths that contain templates here, relative to this directory.
-templates_path = ['_templates']
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -68,10 +71,34 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = [
-    '_static',
+    "_static",
     # "../../test/integration"
 ]
 
+html_logo = "yfpy-logo.png"
+# see https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html for html_theme_options details
+html_theme_options = {
+    # "analytics_id": "G-XXXXXXXXXX",  #  Provided by Google in your dashboard
+    "analytics_anonymize_ip": False,
+    "logo_only": True,
+    "display_version": True,
+    "prev_next_buttons_location": "both",
+    "style_external_links": True,
+    "vcs_pageview_mode": "",
+    # "style_nav_header_background": "white",
+    # Toc options
+    "collapse_navigation": False,
+    "sticky_navigation": True,
+    "navigation_depth": -1,
+    "includehidden": True,
+    "titles_only": False
+}
+
+
+def setup(app):
+    app.add_css_file("custom.css")
+
+
 # -- Extension configuration -------------------------------------------------
 
 # configure sphinx.ext.intersphinx
@@ -82,9 +109,9 @@
 # configure sphinx.ext.autosummary & sphinx_autodoc_typehints
 autosummary_generate = True  # activate sphinx.ext.autosummary
 autoclass_content = "both"  # add __init__ documentation (params, attributes) to class summaries
-html_show_sourcelink = False  # remove 'view source code' from top of html pages
+html_show_sourcelink = False  # remove "view source code" from top of html pages
 autodoc_inherit_docstrings = True  # inherit docstrings from base class if no docstring is supplied
-set_type_checking_flag = True  # enable 'expensive' imports for sphinx_autodoc_typehints
+set_type_checking_flag = True  # enable "expensive" imports for sphinx_autodoc_typehints
 add_module_names = False  # remove the Python namespaces from class/method signatures
 
 # configure myst_parser

diff --git a/docs-sphinx/source/yfpy-logo.png b/docs-sphinx/source/yfpy-logo.png
diff --git a/requirements-dev.txt b/requirements-dev.txt
@@ -2,5 +2,5 @@ twine==4.0.0
 sphinx==4.5.0
 sphinx-rtd-theme==1.0.0
 sphinx-autodoc-typehints==1.18.1
-pydata-sphinx-theme==0.8.1
+sphinx-rtd-dark-mode==1.2.4
 myst-parser==0.17.2
diff --git a/test/integration/conftest.py b/test/integration/conftest.py
@@ -11,7 +11,7 @@
 from yfpy.query import YahooFantasySportsQuery
 
 """
-Example public Yahoo league uRL: "https://archive.fantasysports.yahoo.com/nfl/2014/729259"
+Example public Yahoo league URL: "https://archive.fantasysports.yahoo.com/nfl/2014/729259"
 
 Example vars using public Yahoo leagues still require auth through a personal Yahoo account: see README.md
 """
@@ -91,9 +91,9 @@ def chosen_week() -> int:
 def chosen_date() -> str:
     """Set Yahoo Fantasy Sports chosen date for testing."""
 
-    # chosen_date = "2013-04-15"  # NHL - 2013
+    chosen_date = "2013-04-15"  # NHL - 2013 (for 2012)
     # chosen_date = "2013-04-16"  # NHL - 2013
-    chosen_date = "2021-10-25"  # NHL - 2021
+    # chosen_date = "2021-10-25"  # NHL - 2021
 
     return chosen_date
 
@@ -149,7 +149,7 @@ def game_key() -> str:
 def game_code() -> str:
     """Set Yahoo Fantasy Sports game code for testing."""
 
-    game_code = "nfl"
+    game_code = "nfl"  # NFL
 
     # game_code = "nhl"  # NHL
 
@@ -160,7 +160,9 @@ def game_code() -> str:
 def team_id() -> int:
     """Set Yahoo Fantasy Sports team ID for testing."""
 
-    team_id = 1
+    team_id = 1  # NFL
+
+    # team_id = 2  # NHL (2012)
 
     return team_id
 
@@ -169,7 +171,9 @@ def team_id() -> int:
 def team_name() -> str:
     """Set Yahoo Fantasy Sports team name for testing."""
 
-    team_name = "Legion"
+    team_name = "Legion"  # NFL
+
+    # team_name = "The Bateleurs"  # NHL (2012)
 
     return team_name