#5 Enhance documentation

PRUNplanner · Nov 3, 2023 · e5fd4d3 · e5fd4d3
1 parent 5d0fa05
commit e5fd4d3
Show file tree

Hide file tree

Showing 10 changed files with 137 additions and 71 deletions.
diff --git a/README.md b/README.md
@@ -3,6 +3,7 @@
 [![PyPI - Version](https://img.shields.io/pypi/v/fio-wrapper.svg)](https://pypi.org/project/fio-wrapper)
 [![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fio-wrapper.svg)](https://pypi.org/project/fio-wrapper)
 [![License: MIT](https://img.shields.io/badge/license-MIT-C06524)](https://github.com/jplacht/fio_wrapper/blob/master/LICENSE.md)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/fio-wrapper)
 
 ---
 
@@ -12,46 +13,6 @@
 - Documentation: [https://jplacht.github.io/fio_wrapper/](https://jplacht.github.io/fio_wrapper/)
 - PyPi Package: [https://pypi.org/project/fio-wrapper/](https://pypi.org/project/fio-wrapper/)
 
-# Endpoints
-The following endpoints are available as classes of the wrapper:
-```markdown
-# Planet
-- /planet/{Planet}
-- /planet/allplanets
-- /planet/allplanets/full
-- /planet/sites/{Planet}
-- /planet/search
-
-# Material
-- /material/{MaterialTicker}
-- /material/allmaterials
-- /material/category/{CategoryName}
-
-# Building
-- /building/{BuildingTicker}
-- /building/allbuildings
-
-# Recipe
-- /recipes/{Ticker}
-- /recipes/allrecipes
-
-# Exchange
-- /exchange/{ExchangeTicker}
-- /exchange/all
-- /exchange/full
-- /exchange/orders/{CompanyCode}
-- /exchange/orders/{CompanyCode}/{ExchangeCode}
-
-# LocalMarket
-- /localmarket/planet/{Planet}
-- /localmarket/planet/{Planet}/{Type}
-- /localmarket/shipping/source/{Planet}
-- /localmarket/shipping/destination/{Planet}
-- /localmarket/company/{Company}
-
-```
-
-
 # Usage
 ## Installation
 ```python

diff --git a/docs/index.md b/docs/index.md
@@ -1,3 +1,10 @@
+[![PyPI - Version](https://img.shields.io/pypi/v/fio-wrapper.svg)](https://pypi.org/project/fio-wrapper)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/fio-wrapper.svg)](https://pypi.org/project/fio-wrapper)
+[![License: MIT](https://img.shields.io/badge/license-MIT-C06524)](https://github.com/jplacht/fio_wrapper/blob/master/LICENSE.md)
+![PyPI - Downloads](https://img.shields.io/pypi/dm/fio-wrapper)
+
+---
+
 [FIO](https://doc.fnar.net/) API wrapper with [pydantic](https://github.com/pydantic/pydantic) data validation and easy-to-use querying. **fio_wrapper** implements the most used endpoints of Prosperous Universes community game data API.
 
 Source Code: [https://github.com/jplacht/fio_wrapper](https://github.com/jplacht/fio_wrapper)

diff --git a/docs/routes.md b/docs/routes.md
@@ -0,0 +1,39 @@
+# FIO REST API endpoints
+
+FIO Wrapper includes the most commonly used FIO REST API endpoints.
+
+## Planet
+
+- `GET` /planet/{Planet}
+- `GET` /planet/allplanets
+- `GET` /planet/allplanets/full
+- `GET` /planet/sites/{Planet}
+- `POST` /planet/search
+
+## Material
+- `GET` /material/{MaterialTicker}
+- `GET` /material/allmaterials
+- `GET` /material/category/{CategoryName}
+
+## Building
+- `GET` /building/{BuildingTicker}
+- `GET` /building/allbuildings
+
+## Recipes
+- `GET` /recipes/{Ticker}
+- `GET` /recipes/allrecipes
+
+## Exchange
+- `GET` /exchange/{ExchangeTicker}
+- `GET` /exchange/all
+- `GET` /exchange/full
+- `GET` /exchange/orders/{CompanyCode}
+- `GET` /exchange/orders/{CompanyCode}/{ExchangeCode}
+
+## LocalMarket
+- `GET` /localmarket/planet/{Planet}
+- `GET` /localmarket/planet/{Planet}/{Type}
+- `GET` /localmarket/shipping/source/{Planet}
+- `GET` /localmarket/shipping/destination/{Planet}
+- `GET` /localmarket/company/{Company}
+
diff --git a/docs/usage.md b/docs/usage.md
@@ -11,14 +11,11 @@ from fio_wrapper import FIO
 fio = FIO()
 
 material = fio.Material.get("DW")
-print(material)
+
 print(material.model_dump_json())
 ```
 
 This will print the material information of Drinking Water as MaterialModel and it's JSON.
-```python
-MaterialId='4fca6f5b5e6c3b8a1b887c6dc99db146' CategoryName='consumables (basic)' CategoryId='3f047ec3043bdd795fd7272d6be98799' Name='drinkingWater' Ticker='DW' Weight=0.10000000149011612 Volume=0.10000000149011612 UserNameSubmitted='SAGANAKI' Timestamp=datetime.datetime(2023, 10, 28, 19, 26, 21, 831707)
-```
 
 ```json
 {

diff --git a/fio_wrapper/endpoints/endpoints_v1/planet.py b/fio_wrapper/endpoints/endpoints_v1/planet.py
@@ -22,6 +22,8 @@
 
 
 class Planet(AbstractPlanet):
+    """Planet endpoint wrapper"""
+
     def __init__(self, adapter: FIOAdapter) -> None:
         self._adapter: FIOAdapter = adapter
 
@@ -110,34 +112,34 @@ def search(
         must_have_adm: bool = False,
         must_have_shy: bool = False,
         distance_checks: List[str] = [],
-    ):
+    ) -> PlanetFullList:
         """Performs a search request towards FIO to find a planet matching the search parameters
 
         Args:
-            materials (List[str], optional): List of materials to search for, e.g. ["FEO", "LST"]. Defaults to [].
-            include_rocky (bool, optional): Planet can be Rocky. Defaults to False.
-            include_gaseous (bool, optional): Planet can be Gaseous. Defaults to False.
-            include_low_gravity (bool, optional): Planet can be low gravity. Defaults to False.
-            include_high_gravity (bool, optional): Planet can be high gravity. Defaults to False.
-            include_low_pressure (bool, optional): Planet can be low pressure. Defaults to False.
-            include_high_pressure (bool, optional): Planet can be high pressure. Defaults to False.
-            include_low_temperature (bool, optional): Planet can be low temperature. Defaults to False.
-            include_high_temperature (bool, optional): Planet can be high temperature. Defaults to False.
-            must_be_fertile (bool, optional): Planet must be Fertile. Defaults to False.
-            must_have_localmarket (bool, optional): Planet must have a Local Market. Defaults to False.
-            must_have_cogc (bool, optional): Planet must have a Chamber of Glboal Commerce. Defaults to False.
-            must_have_war (bool, optional): Planet must have warehouses. Defaults to False.
-            must_have_adm (bool, optional): Planet must have a Planetary Administration Center. Defaults to False.
-            must_have_shy (bool, optional): Planet must have a Shipyard. Defaults to False.
-            distance_checks (List[str], optional): List of other planets to check distance to, e.g. ["ANT", "MOR"]. Defaults to [].
+            materials (List[str], optional): List of materials to search for, e.g. ["FEO", "LST"].
+            include_rocky (bool, optional): Planet can be Rocky.
+            include_gaseous (bool, optional): Planet can be Gaseous.
+            include_low_gravity (bool, optional): Planet can be low gravity.
+            include_high_gravity (bool, optional): Planet can be high gravity.
+            include_low_pressure (bool, optional): Planet can be low pressure.
+            include_high_pressure (bool, optional): Planet can be high pressure.
+            include_low_temperature (bool, optional): Planet can be low temperature.
+            include_high_temperature (bool, optional): Planet can be high temperature.
+            must_be_fertile (bool, optional): Planet must be Fertile.
+            must_have_localmarket (bool, optional): Planet must have a Local Market.
+            must_have_cogc (bool, optional): Planet must have a Chamber of Glboal Commerce.
+            must_have_war (bool, optional): Planet must have warehouses.
+            must_have_adm (bool, optional): Planet must have a Planetary Administration Center.
+            must_have_shy (bool, optional): Planet must have a Shipyard.
+            distance_checks (List[str], optional): List of other planets to check distance to, e.g. ["ANT", "MOR"].
 
         Raises:
             PlanetSearchMaterialsInvalid: _description_
             PlanetSearchDistanceChecksInvalid: _description_
             PlanetSearchInvalidRequest: _description_
 
         Returns:
-            _type_: _description_
+            PlanetFullList: List of Planets with full information as List[PlanetFull]
         """
         if not validate_planet_search_materials(materials=materials):
             raise PlanetSearchMaterialsInvalid(

diff --git a/fio_wrapper/fio.py b/fio_wrapper/fio.py
@@ -1,4 +1,4 @@
-"""Provide the FIO class to access game data through FIO REST API endpoints
+"""FIO class to access game data through FIO REST API endpoints
 """
 
 from fio_wrapper.fio_adapter import FIOAdapter

diff --git a/fio_wrapper/fio_adapter.py b/fio_wrapper/fio_adapter.py
@@ -1,4 +1,7 @@
-from typing import Dict, List, Tuple
+"""Request adapter performing actual API calls towards FIO endpoints
+"""
+
+from typing import Dict, Tuple
 import requests
 from urllib3.exceptions import InsecureRequestWarning
 from fio_wrapper.urls import URLs
@@ -67,7 +70,6 @@ def get(
         Args:
             endpoint (str): URL
             params (Dict, optional): GET parameters. Defaults to None.
-            data (Dict, optional): GET data. Defaults to None.
             err_codes (list, optional): List of error codes to handle in calling function. Defaults to [].
 
         Returns:

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -4,8 +4,10 @@ repo_url: "https://github.com/jplacht/fio_wrapper"
 
 theme:
   name: "material"
+  plugins:
+    - optimize
+    - typeset
   palette:
-
   # Palette toggle for light mode
   - media: "(prefers-color-scheme: light)"
     scheme: light
@@ -19,6 +21,17 @@ theme:
     toggle:
       icon: material/brightness-4
       name: Switch to light mode
+  features:
+  - search.suggest
+  - search.highlight
+  - content.tabs.link
+  - navigation.indexes
+  - content.tooltips
+  - navigation.path
+  - content.code.annotate
+  - content.code.copy
+  - content.code.select
+  - navigation.sections
 
 plugins:
   - mkdocstrings:
@@ -28,22 +41,52 @@ plugins:
           options:
             show_source: false
             show_bases: false
+            show_root_heading: true
+            show_if_no_docstring: true
+            inherited_members: true
+            members_order: source
+            separate_signature: true
+            unwrap_annotated: true
+            filters: ["!^_"]
+            merge_init_into_class: true
+            docstring_section_style: table
+            signature_crossrefs: true
+            show_symbol_type_heading: true
+            show_symbol_type_toc: true
   - search
+  - coverage:
+      page_name: coverage  # default
+      html_report_dir: coverage  # default
 
 markdown_extensions:
+  - abbr
+  - attr_list
   - pymdownx.highlight:
       anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
   - pymdownx.superfences
+  - pymdownx.critic
+  - pymdownx.caret
+  - pymdownx.keys
+  - pymdownx.mark
+  - pymdownx.tilde
 
 nav:
-  - FIO Wrapper: index.md
+  - Introduction: index.md
   - Usage: usage.md
-  - FIO(): fio.md
-  - Endpoints:
+  - Available Routes: 'routes.md'  
+  - Components:
+    - FIO Class: fio.md
+    - FIO Adapter: fio_adapter.md
+  - Endpoints (FIO v.1): 
     - Planet: 'endpoints/planet.md'
     - Building: 'endpoints/building.md'
     - Recipe: 'endpoints/recipe.md'
     - Material: 'endpoints/material.md'
     - Exchange: 'endpoints/exchange.md'
     - LocalMarket: 'endpoints/localmarket.md'
-  - FIO Adapter: fio_adapter.md
+  - Test Coverage:
+    - Coverage Report: coverage.md
diff --git a/poetry.lock b/poetry.lock
diff --git a/pyproject.toml b/pyproject.toml
@@ -36,3 +36,4 @@ optional = true
 mkdocs = "^1.5.3"
 mkdocstrings = {extras = ["python"], version = "^0.23.0"}
 mkdocs-material = "^9.4.7"
+mkdocs-coverage = "^1.0.0"