rework sphinx setup, update documentation

drunsinn · Jan 6, 2025 · 6d4455d · 6d4455d
1 parent 000cbc6
commit 6d4455d
Show file tree

Hide file tree

Showing 9 changed files with 127 additions and 365 deletions.
diff --git a/.gitignore b/.gitignore
@@ -110,3 +110,4 @@ venv.bak/
 *.todo
 /extern_docs
 .vscode/
+docs/source/README.md
diff --git a/README.md b/README.md
@@ -1,26 +1,22 @@
-# XSteam
+# pyXSteam
 
-Original Released by Magnus Holmgren for Matlab and Excel:
-<http://xsteam.sourceforge.net> and/or <http://www.x-eng.com>
+pyXSteam is a Python library designed for calculating thermodynamic properties of water and steam based on the [IAPWS](http://www.iapws.org) (International Association for the Properties of Water and Steam) formulations.
 
-At [this github repository](https://github.com/stu314159/xsteam) you can find the/a matlab version.
+This library was ported from the original Matlab released by Magnus Holmgren. The original can be founbd at [Sourceforge](http://xsteam.sourceforge.net) and/or <http://www.x-eng.com>.
 
-XSteam provides (mostly) accurate steam and water properties from 0 -
-1000 bar and from 0 - 2000 °C according to the [IAPWS release IF-97](http://www.iapws.org/relguide/IF97-Rev.pdf). For
-accuracy of the functions in different regions see IF-97 Page 4
+pyXSteam and XSteam provide (mostly) accurate steam and water properties from 0 - 1000 bar and from 0 - 2000 °C according to the [IAPWS release IF-97 (R7-97(2012))](http://www.iapws.org/relguide/IF97-Rev.pdf) . For accuracy of the functions in different regions see IF-97 Page 4. We take no responsibilities for any errors in the code or damage thereby!
 
-Also includes thermal conductivity and viscosity, which are not part of
-the IF97 release.
-* Thermal Conductivity: IAPWS R15-11
-* Viscosity: IAPWS R12-08
-* Surface Tension: IAPWS R1-76(2014)
+Also included are functions for thermal conductivity and viscosity which are not part of R7-97(2012).
 
+ - [IAPWS R15-11: Thermal Conductivity of Ordinary Water Substance](http://www.iapws.org/relguide/ThCond.pdf)
+ - [IAPWS R12-08: Viscosity of Ordinary Water Substance](http://www.iapws.org/relguide/visc.pdf)
+ - [IAPWS R1-76(2014): Surface Tension of Ordinary Water Substance](https://www.iapws.org/relguide/Surf-H2O-2014.pdf)
 
-Some effort has been made to include the refined function of more recent releases
-and also functions for calculations on heavy water. This includes:
-* IAPWS R4
-* Surface Tension: IAPWS R5-85(1994)
-* IAPWS R14
+Some effort has been made to include the refined function of more recent releases and also functions for calculations on heavy water. This implementation is still in progress, these function should not be used. This includes:
+
+ - IAPWS R4 (deprecated)
+ - IAPWS R5-85(1994)
+ - IAPWS R14
 
 
 ## Contributors
@@ -32,75 +28,107 @@ In chronological order:
 - gonmolina
 - xjtu-blacksmith
 
+## Documentation
 
-## Requirements
+Check out [pyXSteam at readthedocs](https://pyxsteam.readthedocs.io)
 
-There are no requirements for installing pyXSteam with Python 3.6 and up.
+## Requirements
 
-Tests require numpy, demos require numpy and matplotlib
+There are no requirements for installing pyXSteam with Python 3.8 and up. The demos require `numpy` and `matplotlib`.
 
-## Install
+### Tests
 
-run `python3 setup.py install`
+Tests require `pytest` and `numpy`
 
-To run unittests you need two additional packages: `pytest` and `numpy`. After installing both, just run pytest in
-the base directory. The tests use some fixed values from the documentation to make sure that every coefficient
-and formula works as intended.
+## Install
 
-To test if setup was successful, run `python3 bin/pyXSteamDemo.py`. This will require numpy and matplotlib to be installed.
+run `pip install pyXSteam`
 
-## Nomenclature
+To run unittests you need two additional packages: `pytest` and `numpy`. After installing both, just run pytest in the base directory. The tests use some fixed values from the documentation to make sure that every coefficient and formula works as intended.
 
-All Functions follow the same naming schema: First the wanted property,
-then a underscore `_`, then the wanted input properties Example:
-`t_ph` is temperature as a function of pressure and enthalpy. For a list
-of valid functions se below:
-
-| Property | Description                                                  |
-|----------|--------------------------------------------------------------|
-| t        | Temperature (°C or °F)                                       |
-| p        | Pressure (bar or psi)                                        |
-| h        | Enthalpy (kJ/kg or btu/lb)                                   |
-| v        | Specific volume (m3/kg or ft\^3/lb)                          |
-| rho      | Density (kg/m3 or lb/ft\^3)                                  |
-| s        | Specific entropy (kJ/(kg °C) or btu/(lb °F))                 |
-| u        | Specific internal energy (kJ/kg or btu/lb)                   |
-| Cp       | Specific isobaric heat capacity (kJ/(kg °C) or btu/(lb °F))  |
-| Cv       | Specific isochoric heat capacity (kJ/(kg °C) or btu/(lb °F)) |
-| w        | Speed of sound (m/s or ft/s)                                 |
-| my       | Viscosity (N s/m\^2 or lbm/ft/hr)                            |
-| tc       | Thermal Conductivity (W/(m °C) or btu/(h ft °F))             |
-| st       | Surface Tension (N/m or lb/ft)                               |
-| x        | Vapor fraction                                               |
-| vx       | Vapor Volume Fraction                                        |
+To test if setup was successful, run `pyXSteamDemo`. This will require numpy and matplotlib to be installed.
 
 ## Usage
 
 Simple Example:
 
+```
     from pyXSteam.XSteam import XSteam
     steamTable = XSteam(XSteam.UNIT_SYSTEM_MKS)
     print(steamTable.hL_p(220.0))
+```
 
 By using the unitSystem Parameter, you can tell XSteam witch Unit System you are using.
 
+```
     steamTable = XSteam(XSteam.UNIT_SYSTEM_MKS) # m/kg/sec/°C/bar/W
     steamTable = XSteam(XSteam.UNIT_SYSTEM_FLS) # ft/lb/sec/°F/psi/btu
     steamTable = XSteam(XSteam.UNIT_SYSTEM_BARE) # m/kg/sec/K/MPa/W
+```
 
 To enable logging, add the following lines to your code:
 
+```
     import logging
     logging.basicConfig(level=logging.INFO)
+```
 
 or alternatively
 
+```
     import logging
     logger = logging.getLogger('pyXSteam')
     logger.setLevel(logging.DEBUG)
     sh = logging.StreamHandler()
     sh.setFormatter(logging.Formatter('%(name)s - %(levelname)s - %(message)s'))
     logger.addHandler(sh)
+```
+
+## Related projects
+
+Implementations of the IAPWS releases are also available for other programming languages:
+
+- Matlab and Excel: [xsteam](http://xsteam.sourceforge.net)
+- Matlab: [xsteam](https://github.com/stu314159/xsteam)
+- .NET: [XSteamNET](https://github.com/rogerlew/XSteamNET)
+
+
+## Notes
+
+### Density (rho)
+
+Density is calculated as 1/v. See section for Specific volume
+
+### Viscosity
+
+Viscosity is not part of IAPWS Steam IF97. Equations from "Revised Release on the IAPWS Formulation 1985 for the Viscosity of Ordinary Water Substance", 2003 are used. Viscosity in the mixed region (4) is interpolated according to the density. This is not true since it will be two phases.
+
+### Thermal conductivity
+
+Revised release on the IAPS Formulation 1985 for the Thermal Conductivity of ordinary water substance (IAPWS 1998)
+
+## Nomenclature
+
+All Functions follow the same naming schema: First the wanted property, then a underscore `_`, then the wanted input properties Example: `t_ph` is temperature as a function of pressure and enthalpy. For a list of valid functions se below:
+
+| Property | Description                                                  |
+|----------|--------------------------------------------------------------|
+| t        | Temperature (°C or °F)                                       |
+| p        | Pressure (bar or psi)                                        |
+| h        | Enthalpy (kJ/kg or btu/lb)                                   |
+| v        | Specific volume (m3/kg or ft\^3/lb)                          |
+| rho      | Density (kg/m3 or lb/ft\^3)                                  |
+| s        | Specific entropy (kJ/(kg °C) or btu/(lb °F))                 |
+| u        | Specific internal energy (kJ/kg or btu/lb)                   |
+| Cp       | Specific isobaric heat capacity (kJ/(kg °C) or btu/(lb °F))  |
+| Cv       | Specific isochoric heat capacity (kJ/(kg °C) or btu/(lb °F)) |
+| w        | Speed of sound (m/s or ft/s)                                 |
+| my       | Viscosity (N s/m\^2 or lbm/ft/hr)                            |
+| tc       | Thermal Conductivity (W/(m °C) or btu/(h ft °F))             |
+| st       | Surface Tension (N/m or lb/ft)                               |
+| x        | Vapor fraction                                               |
+| vx       | Vapor Volume Fraction                                        |
+
 
 ## Available Functions
 
@@ -241,25 +269,18 @@ or alternatively
 | x_ph     | vapor fraction as a function of pressure and enthalpy |
 | x_ps     | vapor fraction as a function of pressure and entropy  |
 
-## vapor volume fraction
+### vapor volume fraction
 | Function | Description                                                  |
 |----------|--------------------------------------------------------------|
 | vx_ph    | vapor volume fraction as a function of pressure and enthalpy |
 | vx_ps    | vapor volume fraction as a function of pressure and entropy  |
 
-## Pressure along the Melting and Sublimation Curves
-| Function     | Description                                                        |
-|--------------|--------------------------------------------------------------------|
-| pmelt_t      | Pressure along the melting curve as a function of temperature      |
-| vx_psubl_tps | Pressure along the sublimation curve as a function of temperature  |
-
-# Available Functions for Heavy Water
-| Function | Description                                                   |
-|----------|---------------------------------------------------------------|
-| my_rhoT  | Viscosity as a function of density and temperature            |
-| tc_rhoT  | Thermal conductivity as a function of density and temperature |
-
+### Pressure along the Melting and Sublimation Curves
+| Function | Description                                                        |
+|----------|--------------------------------------------------------------------|
+| pmelt_t  | Pressure along the melting curve as a function of temperature      |
+| psubl_t  | Pressure along the sublimation curve as a function of temperature  |
 
-# Development
+## Development
 - pull requests are always wellcome!
 - code style is enforced by black
diff --git a/docs/Makefile b/docs/Makefile
@@ -16,4 +16,5 @@ help:
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+	cp -f ../README.md ./source/
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -43,6 +43,7 @@
     "sphinx.ext.autodoc",
     "sphinx.ext.githubpages",
     "sphinx_autodoc_typehints",
+    "myst_parser",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -67,7 +68,7 @@
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = []
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = None
@@ -186,6 +187,12 @@
 # -- Extension configuration -------------------------------------------------
 
 set_type_checking_flag = True
-typehints_fully_qualified = True
+
+# -- Options for sphinx_autodoc_typehints ------------------------------------
+typehints_fully_qualified = False
 always_document_param_types = True
 typehints_document_rtype = True
+typehints_use_rtype = True
+typehints_defaults = "comma"
+simplify_optional_unions = True
+typehints_formatter = None
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -1,82 +1,18 @@
-.. pyXSteam documentation master file, created by
-   sphinx-quickstart on Fri Mar  8 16:32:11 2019.
-
-Welcome to pyXSteam's documentation!
-####################################
-
-Original Released by Magnus Holmgren for Matlab and Excel: <http://xsteam.sourceforge.net> and/or <http://www.x-eng.com>
-
-XSteam provides (mostly) accurate steam and water properties from 0 - 1000 bar and from 0 - 2000 °C according to the [IAPWS release IF-97](http://www.iapws.org/relguide/IF97-Rev.pdf). For accuracy of the functions in different regions see IF-97 Page 4
-
-Also includes thermal conductivity and viscosity, which are not part of the IF97 release.
-* `Thermal Conductivity: (IAPWS 1998) <http://www.iapws.org/relguide/ThCond.pdf>`_
-
-This Python Library is based on the original XSteam Library for Matlab and Excel from Magnus Holmgren, www.x-eng.com. We take no responsibilities for any errors in the code or damage thereby!
-
-See README.md for examples
-
-Some effort has been made to include the refined function of more recent releases and also functions for calculations on heavy water. This includes:
-* IAPWS R4
-* IAPWS R14
-
-Usage Examples
-**************
-Check out the examples given in :doc:`pyXSteamDemo` for a quick overview of how to use pyXSteam in different use cases.
-
-Notes
-*****
-Density (rho)
-=============
-Density is calculated as 1/v. See section for Specific volume
-
-Viscosity
-=========
-Viscosity is not part of IAPWS Steam IF97. Equations from "Revised Release on the IAPWS Formulation 1985 for the Viscosity of Ordinary Water Substance", 2003 are used. Viscosity in the mixed region (4) is interpolated according to the density. This is not true since it will be two phases.
-
-Thermal conductivity
-====================
-Revised release on the IAPS Formulation 1985 for the Thermal Conductivity of ordinary water substance (IAPWS 1998)
-
-Nomenclature
-============
-All Functions follow the same naming schema: First the wanted property, then a underscore `_`, then the wanted input properties Example: `t_ph` is temperature as a function of pressure and enthalpy. For a list of valid functions se below:
-
-========   ============================================================
-Property   Description
-========   ============================================================
-t          Temperature (°C or °F)
-p          Pressure (bar or psi)
-h          Enthalpy (kJ/kg or btu/lb)
-v          Specific volume (m3/kg or ft\^3/lb)|
-rho        Density (kg/m3 or lb/ft\^3)
-s          Specific entropy (kJ/(kg °C) or btu/(lb °F))
-u          Specific internal energy (kJ/kg or btu/lb)
-Cp         Specific isobaric heat capacity (kJ/(kg °C) or btu/(lb °F))
-Cv         Specific isochoric heat capacity (kJ/(kg °C) or btu/(lb °F))
-w          Speed of sound (m/s or ft/s)
-my         Viscosity (N s/m\^2 or lbm/ft/hr)
-tc         Thermal Conductivity (W/(m °C) or btu/(h ft °F))
-st         Surface Tension (N/m or lb/ft)
-x          Vapor fraction
-vx         Vapor Volume Fraction
-========   ============================================================
-
-Related projects
-================
-
-Implementations of the IAPWS releases are also available for other programming languages:
-
-- Matlab: [xsteam](https://github.com/stu314159/xsteam)
-- .NET: [XSteamNET](https://github.com/rogerlew/XSteamNET)
+======================================
+ Welcome to pyXSteam's documentation!
+======================================
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
-   pyXSteamAvailibleFunctions
+   README.md
    pyXSteam
    pyXSteamDemo
 
+.. automodule:: pyXSteam.XSteam
+   :noindex:
+
 Indices and tables
 ==================