Merge branch '5-gh-pages'

Makefile

@@ -1,6 +1,15 @@
 CONFIG=./pyproject.toml
 PY_FILES:=$(shell find src/property_utils -not -path '*/tests/*' -not -name '__init__.py' -name '*.py')
 
+install-documentation-builder:
+	$(PIP) install mkdocs mkdocs-material 'mkdocstrings[python]'
+
+start-documentation-server:
+	$(INTERPRETER) -m mkdocs serve
+
+deploy-documentation:
+	$(INTERPRETER) -m mkdocs gh-deploy --config-file mkdocs.yml
+
 install-package-linter:
 	$(PIP) install pylint
 

docs/converter_types.md

@@ -0,0 +1 @@
+::: property_utils.units.converter_types

docs/converters.md

@@ -0,0 +1 @@
+::: property_utils.units.converters

docs/descriptors.md

@@ -0,0 +1 @@
+::: property_utils.units.descriptors

docs/feedback.md

@@ -0,0 +1,3 @@
+## Got bugs or an idea for a new feature?
+Great! (well, not if you've got bugs) open up an issue in the project's repo:
+[issues](https://github.com/Maxcode123/property-utils/issues).

docs/index.md

@@ -0,0 +1,17 @@
+`property-utils` is a python library that aims at making programming with physical properties easier. 
+It was created to be used by scientists and engineers with little programming experience.
+
+**What is provided by property-utils?**
+
+### Unit arithmetics  
+You can divide and multiply units to create new units. For example you can create velocity units by dividing length units with time units.
+
+### Unit conversions
+You can easily convert a property from one unit to another by calling a method.
+
+### Property arithmetics
+You can add, subtract, divide and multiply properties to create new properties. For example, you can create a density property by dividing a mass property with a volume property.
+
+---
+
+If you're not sure what all the above mean, head to [Usage](usage.md) to see examples of how they're used.

docs/installation.md

@@ -0,0 +1,10 @@
+You'll need a Python version bigger or equal to 3.8.  
+If you're new to programming this [page](https://wiki.python.org/moin/BeginnersGuide/NonProgrammers) could help with learning resources.  
+
+Once you've got Python setup you can install `property-utils` from your IDE or via pip: 
+```
+pip install property-utils
+```
+
+## Dependencies
+`property-utils`'s only dependency is the [typing-extensions](https://pypi.org/project/typing-extensions/) library.

docs/property.md

@@ -0,0 +1 @@
+::: property_utils.properties.property

docs/terminology.md

@@ -0,0 +1,7 @@
+## Unit descriptors (or just units)
+Throughout `property-utils` the term **unit descriptor** is used to denote a specific
+measurement unit of a physical property; it can, for example, refer to Celcius (°C) but not to temperature units in general.
+
+## Generic unit descriptors (or just generics)
+Throughout `property-utils` the term **generic descriptor** is used to denote a type of
+measurement units; it can, for example, refer to length units but not to meters, inches, etc.

docs/usage.md

@@ -0,0 +1,250 @@
+This sections assumes the reader is acquainted with the terms in [Terminology](terminology.md).
+
+## Unit arithmetics
+
+### Create composite units
+
+Units can be created by multiplying and dividing base units:
+
+```py linenums="1"
+from property_utils.units import JOULE, MOL, KELVIN, METER
+
+thermal_capacity_units = JOULE / MOL / KELVIN
+molar_volume_units = MOL / METER**3
+print("thermal_capacity_units =", thermal_capacity_units)
+print("molar_volume_units =", molar_volume_units)
+```
+
+Result:
+
+```
+thermal_capacity_units = J / K / mol
+molar_volume_units = mol / (m^3)
+```
+
+### Compare units
+
+Units can be compared with other units.  
+The `isinstance` method checks if a unit belongs to some specific unit type.
+
+```py linenums="1"
+from property_utils.units import WATT, PowerUnit, EnergyUnit
+
+print(WATT.isinstance(PowerUnit))
+print(WATT.isinstance(EnergyUnit))
+```
+
+Result:
+
+```
+True
+False
+```
+
+The `isinstance_equivalent` method checks if a unit is equivalent to some other
+generic unit.
+
+```py linenums="1"
+from property_utils.units import (
+    WATT,
+    PowerUnit,
+    EnergyUnit,
+    TimeUnit,
+    ForceUnit,
+    LengthUnit,
+    MassUnit,
+)
+
+print(WATT.isinstance_equivalent(PowerUnit))
+print(WATT.isinstance_equivalent(EnergyUnit / TimeUnit))
+print(WATT.isinstance_equivalent(ForceUnit * LengthUnit / TimeUnit))
+print(WATT.isinstance_equivalent(MassUnit * LengthUnit**2 / TimeUnit**3))
+```
+
+Result:
+
+```
+True
+True
+True
+True
+```
+
+### SI units
+Any unit can be converted to si units with the `si` method.
+
+```py linenums="1"
+from property_utils.units import BTU, RANKINE, FOOT, CENTI_METER, KILO_CALORIE
+
+print((BTU / FOOT**2 / RANKINE).si())
+print((CENTI_METER**3).si())
+print(KILO_CALORIE.si())
+```
+
+Result:
+
+```
+J / (m^2) / K
+(m^3)
+J
+```
+
+### Simplify composite units
+Composite units may contain same units in the numerator and denominator.  
+The `simplified` method removes common units from the numerator and denominator.
+
+```py linenums="1"
+from property_utils.units import METER, SECOND
+
+velocity_units = METER / SECOND
+acceleration_units = velocity_units / SECOND
+
+print("acceleration_units =", acceleration_units)
+print("acceleration_units simplified =", acceleration_units.simplified())
+```
+
+Result:
+
+```
+acceleration_units = m / s / s
+acceleration_units simplified = m / (s^2)
+```
+
+The `simplified` method also merges common units.
+
+```py linenums="1"
+from property_utils.units import METER
+
+length_units = METER
+area_units = length_units * length_units
+
+print("area_units =", area_units)
+print("area_units simplified =", area_units.simplified())
+```
+
+Result:
+
+```
+area_units = m * m
+area_units simplified = (m^2)
+```
+
+## Unit conversions
+Any property can be converted to chosen units with `to_unit`:
+
+```py linenums="1"
+from property_utils.properties import p
+from property_utils.units import WATT, METER, KELVIN, BTU, FOOT, RANKINE, HOUR
+
+heat_transfer_coeff = p(50, WATT / METER**2 / KELVIN)
+print(
+    "heat_transfer_coeff =",
+    heat_transfer_coeff.to_unit(BTU / HOUR / FOOT**2 / RANKINE),
+)
+```
+
+Result:
+
+```
+heat_transfer_coeff = 8.805115955164156 Btu / (ft^2) / hr / °R
+```
+
+Converting to SI units is easier with `to_si`:
+
+```py linenums="1"
+from property_utils.properties import p
+from property_utils.units import GRAM, CENTI_METER
+
+area_density = p(12, GRAM / CENTI_METER**2)
+
+print("area_density =", area_density)
+print("area_density (SI) =", area_density.to_si())
+```
+
+Result:
+
+```
+area_density = 12 g / (cm^2)
+area_density (SI) = 120.0 kg / (m^2)
+```
+
+## Property arithmetics
+
+### Addition - Subtraction
+
+Properties can be added and subtracted to and from each other:
+
+``` py linenums="1"
+from property_utils.properties import p
+from property_utils.units import BAR
+
+pressure_1 = p(15, BAR)
+pressure_2 = p(2, BAR)
+print("pressure_1 + pressure_2 =", pressure_1 + pressure_2)
+print("pressure_1 - pressure_2 =", pressure_1 - pressure_2)
+```
+
+Result:
+
+```
+pressure_1 + pressure_2 = 17 bar
+pressure_1 - pressure_2 = 13 bar
+```
+
+Properties with different units can be added to each other. The result is always calculated in the units 
+of the left operand.
+
+```py linenums="1"
+from property_utils.properties import p
+from property_utils.units import BAR, PSI
+
+pressure_1 = p(5, BAR)
+pressure_2 = p(30, PSI)
+print("pressure_1 + pressure_2 =", pressure_1 + pressure_2)
+print("pressure_2 + pressure_1 =", pressure_2 + pressure_1)
+```
+
+Result:
+
+```
+pressure_1 + pressure_2 = 7.068423447648202 bar
+pressure_2 + pressure_1 = 102.519 psi
+```
+
+### Multiplication - Division
+
+Properties can be multiplied and divided by numerics:
+
+```py linenums="1"
+from property_utils.properties import p
+from property_utils.units import KELVIN
+
+temperature = p(773.15, KELVIN)
+print("2*temperature =", 2*temperature)
+print("temperature/2 =", temperature/2)
+```
+
+Result:
+
+```
+2*temperature = 1546.3 K
+temperature/2 = 386.575 K
+```
+
+Properties can also be multiplied and divided with each other:
+
+```py linenums="1"
+from property_utils.properties import p
+from property_utils.units import KELVIN, JOULE, KILO_GRAM
+
+thermal_capacity = p(4200, JOULE/KELVIN/KILO_GRAM)
+temperature_diff = p(57, KELVIN)
+enthalpy = thermal_capacity * temperature_diff
+print("enthalpy =", thermal_capacity*temperature_diff)
+```
+
+Result:
+
+```
+enthalpy = 239400 J / kg
+```

docs/validated_property.md

@@ -0,0 +1 @@
+::: property_utils.properties.validated_property

mkdocs.yml

@@ -0,0 +1,50 @@
+site_name: property-utils
+site_url: https://maxcode123.github.io/property-utils/
+nav:
+  - Get started:
+    - What is property-utils?: index.md
+    - Installation: installation.md
+    - Terminology: terminology.md
+    - Usage: usage.md
+
+  - API Documentation:
+    - properties:
+      - property: property.md
+      - validated property: validated_property.md
+    - units:
+      - descriptors: descriptors.md
+      - converters: converters.md
+      - converter types: converter_types.md
+
+  - Feedback: feedback.md
+
+theme:
+  name: material
+  features:
+    - navigation.tabs
+    - navigation.tabs.sticky
+    - navigation.sections
+    - navigation.path
+    - content.code.copy
+  palette:
+    - scheme: default
+      toggle:
+        icon: material/brightness-7
+        name: Switch to dark mode
+    - scheme: slate
+      toggle:
+        icon: material/brightness-4
+        name: Switch to light mode
+
+plugins:
+- mkdocstrings
+- search
+
+markdown_extensions:
+  - pymdownx.highlight:
+      anchor_linenums: true
+      line_spans: __span
+      pygments_lang_class: true
+  - pymdownx.inlinehilite
+  - pymdownx.snippets
+  - pymdownx.superfences