Setup documentation with mkdocs

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 to Tree.ly FlexCo and FMM GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -2,30 +2,37 @@
 
 An open source Python library for yield tables.
 
-## Getting Started
+## Quickstart
 
 Download the latest version of the library from PyPI:
 
 ```bash
 pip install openyieldtables
 ```
 
-### Usage
+Import the library and load a yield table:
 
-...
+```python
+from openyieldtables.yieldtables import (
+    get_yield_table_data,
+    get_yield_tables_meta,
+)
 
-## Documentation
+# Get the metadata of all available yield tables
+yield_tables_meta = get_yield_tables_meta()
 
-You can find the documentation [here](https://openyieldtables.readthedocs.io/en/latest/).
+# Get the data of a yield table by its ID
+yield_table = get_yield_table(1)
+```
 
-## Contributing
+## Documentation
 
-We are happy about every contribution! Please follow our [contribution guideline](CONTRIBUTING.md).
+You can find the documentation [here](https://openyieldtables.readthedocs.io/latest/).
 
-## Local Development
+## Contributing
 
-For development on `openyieldtables` check out our [development docs](CONTRIBUTING.md#development).
+We are happy about every contribution! Please follow our [contribution guideline](https://openyieldtables.readthedocs.io/latest/contributing).
 
-## Who is behind openyieldtables?
+## About
 
 `openyieldtables` is maintained by [Tree.ly](https://tree.ly) and [FMM](https://www.fmm.at/).

docs/about.md

@@ -0,0 +1,7 @@
+# About
+
+The `openyieldtables` library is maintained by [Tree.ly](https://tree.ly) and [FMM](https://www.fmm.at/).
+
+## License
+
+This project is licensed under the MIT License - see the [LICENSE](https://github.com/treely/openyieldtables/blob/main/LICENSE.md) file for details.

CONTRIBUTING.md → docs/contributing.md

@@ -53,14 +53,14 @@ via our websites: [Tree.ly](https://tree.ly), [FMM](https://www.fmm.at/).
 
 ### Installation
 
-1. **Clone the Repository**
+**Clone the Repository**
 
 ```bash
 git clone git@github.com:treely/openyieldtables.git
 cd path/to/openyieldtables
 ```
 
-2. **Install the dependencies**
+**Install the dependencies**
 
 ```bash
 poetry install
@@ -114,3 +114,17 @@ To run the pre-commit checks manually, use:
 ```bash
 poetry run pre-commit run --all-files
 ```
+
+### Documentation
+
+We use `mkdocs` for documentation. To run the documenation locally at [http://127.0.0.1:8000](http://127.0.0.1:8000), use:
+
+```bash
+poetry run mkdocs serve
+```
+
+To build the documentation, use:
+
+```bash
+poetry run mkdocs build
+```

docs/data_model.md

@@ -0,0 +1,57 @@
+# Data Model
+
+The `openyieldtables` library uses [pydantic](https://docs.pydantic.dev/latest/) to model the data structure.
+
+## Raw Data
+
+The underlying data is structured in a way that allows for easy access. The raw data is stored in CSV files and is loaded into the library using the provided [models](data_model.md#models).
+
+The CSV files are structured as follows:
+
+* `yield_tables_meta.csv`: Contains metadata about the available yield tables.
+    - `id`: The unique identifier of the yield table.
+    - `name`: The name of the yield table.
+    - `country_codes`: The ISO 3166-1 alpha-2 country codes of the countries the yield table is applicable to.
+    - `type`: The type of the yield table (e.g. `dgz_100`).
+    - `source`: The source of the yield table.
+    - `link`: A link to the source of the yield table or the yield table itself.
+    - `yield_value_step`: The step between the yield values.
+    - `age_step`: The step between the ages.
+
+* `yield_tables.csv`: Contains the yield tables.
+    - `yt_id`: The unique identifier of the yield table.
+    - `yt_name`: The name of the yield table.
+    - `age`: The age in years.
+    - `dominant_height`: The dominant height in m.
+    - `middle_height`: The middle height in m.
+    - `diameter`: The diameter in cm.
+    - `taper`: The taper.
+    - `trees_per_ha`: The number of trees per hectare.
+    - `area`: The area in m2.
+    - `volume_per_ha`: The volume per hectare in vfm.
+    - `mean_volume_per_ha`: The mean volume per hectare vfm.
+    - `total_volume_per_ha`: The total volume per hectare vfm.
+    - `annual_volume_grow_per_ha`: The annual volume growth per hectare vfm.
+    - `mean_total_growth_per_ha`: The mean total growth per hectare vfm.
+
+## Models
+
+:::openyieldtables.models.yieldtable.YieldTableMeta
+    options:
+      heading_level: 3
+
+:::openyieldtables.models.yieldtable.YieldClassRow
+    options:
+      heading_level: 3
+
+:::openyieldtables.models.yieldtable.YieldClass
+    options:
+      heading_level: 3
+
+:::openyieldtables.models.yieldtable.YieldTableData
+    options:
+      heading_level: 3
+
+:::openyieldtables.models.yieldtable.YieldTable
+    options:
+      heading_level: 3

docs/functions.md

@@ -0,0 +1,48 @@
+# Functions
+
+:::openyieldtables.yieldtables
+    options:
+      heading_level: 2
+      show_root_full_path: true
+      show_source: false
+
+##Usage
+
+**Get the metadata of all available yield tables**
+
+```python
+from openyieldtables.yieldtables import get_yield_tables_meta
+
+# Get the metadata of all available yield tables
+yield_tables_meta = get_yield_tables_meta() # Returns a list of `YieldTableMeta` objects
+
+# Get the first yield table as dictionary
+yield_table_meta = yield_tables_meta[0].model_dump()
+#> {'id': 1, 'name': 'Fichte_Hochgebirge', 'country_codes': ['AT', 'DE'],...}
+```
+
+**Get the metadata of one specific yield table**
+
+```python
+from openyieldtables.yieldtables import get_yield_table_meta
+
+# Get the metadata of a yield table by its ID
+yield_table_meta = get_yield_table_meta(1) # Returns a `YieldTableMeta` object
+
+# Get the yield table metadata as dictionary
+yield_table_meta_dict = yield_table_meta.model_dump()
+#> {'id': 1, 'name': 'Fichte_Hochgebirge', 'country_codes': ['AT', 'DE'],...}
+```
+
+**Get the data of one specific yield table**
+
+```python
+from openyieldtables.yieldtables import get_yield_table_data
+
+# Get the data of a yield table by its ID
+yield_table_data = get_yield_table_data(1) # Returns a `YieldTable` object
+
+# Get one row of the yield table data as dictionary
+yield_table_data.data[0].yield_classes[0].rows[0].model_dump()
+#> {'age': 20, 'dominant_height': 5.9, 'middle_height': 5.3, 'diameter': 11.5, 'taper': 0.396,...}
+```

docs/index.md

@@ -0,0 +1,28 @@
+# openyieldtables
+
+The `openyieldtables` library is an open source Python library for yield tables.
+
+## Getting Started
+
+Download the latest version of the library from PyPI:
+
+```bash
+pip install openyieldtables
+```
+
+### Usage
+
+Import the library and load a yield table:
+
+```python
+from openyieldtables.yieldtables import (
+    get_yield_table_data,
+    get_yield_tables_meta,
+)
+
+# Get the metadata of all available yield tables
+yield_tables_meta = get_yield_tables_meta() # Returns a list of `YieldTableMeta` objects
+
+# Get the data of a yield table by its ID
+yield_table = get_yield_table(1) # Returns a `YieldTable` object
+```

mkdocs.yml

@@ -0,0 +1,32 @@
+site_name: openyieldtables
+site_description: An open source library for yield tables
+
+theme:
+  name: readthedocs
+
+repo_name: openyieldtables
+repo_url: https://github.com/treely/openyieldtables
+edit_uri: edit/main/docs/
+
+# https://www.mkdocs.org/user-guide/configuration/#validation
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+
+nav:
+  - Overview: index.md
+  - Data model: data_model.md
+  - Functions: functions.md
+  - Contributing: contributing.md
+  - About: about.md
+
+plugins:
+  - search
+  - mkdocstrings:
+      handlers:
+        python:
+          paths: [src]
+          options:
+            show_root_heading: true
+            show_root_full_path: false