From d3ba5f248a160ff13b198f396959524febcefd3b Mon Sep 17 00:00:00 2001 From: Lukasz Mentel Date: Sun, 29 Sep 2024 19:52:01 +0200 Subject: [PATCH] Add api docs for the PhaseTransition model (#181) * add PhaseTransition to model.__all__ * add ScatteringFactor api docs * add Group to models.__all__ and sort alphabetically * add allotrope arg * update module docstring * update module doc * module doc * add module doc * add module doc * add module doc * add module doc * update docs * update vis docs * fix reference --- docs/source/api/api.rst | 29 ++++++-- docs/source/api/electronegativity.rst | 7 -- docs/source/api/mendeleev.cli.rst | 27 ++++++- docs/source/api/mendeleev.ion.rst | 6 -- docs/source/api/mendeleev.models.rst | 48 ------------- docs/source/api/mendeleev.utils.rst | 2 + docs/source/api/mendeleev.vis.bokeh.rst | 20 +----- .../api/mendeleev.vis.periodictable.rst | 23 +----- docs/source/api/mendeleev.vis.plotly.rst | 24 +------ docs/source/api/mendeleev.vis.rst | 35 ---------- docs/source/api/mendeleev.vis.seaborn.rst | 20 +----- docs/source/api/mendeleev.vis.utils.rst | 24 +------ docs/source/api/models.rst | 70 +++++++++++++------ docs/source/api/utils.rst | 5 -- docs/source/api/vis.rst | 38 ---------- mendeleev/cli.py | 2 +- mendeleev/db.py | 2 + mendeleev/fetch.py | 2 + mendeleev/ion.py | 2 + mendeleev/mendeleev.py | 2 +- mendeleev/models.py | 13 ++-- mendeleev/utils.py | 2 + 22 files changed, 126 insertions(+), 277 deletions(-) delete mode 100644 docs/source/api/electronegativity.rst delete mode 100644 docs/source/api/mendeleev.ion.rst delete mode 100644 docs/source/api/mendeleev.models.rst delete mode 100644 docs/source/api/mendeleev.vis.rst delete mode 100644 docs/source/api/utils.rst delete mode 100644 docs/source/api/vis.rst diff --git a/docs/source/api/api.rst b/docs/source/api/api.rst index e526f6f9..fe6647de 100644 --- a/docs/source/api/api.rst +++ b/docs/source/api/api.rst @@ -4,23 +4,40 @@ API Reference ************* -Here you'll find API documentation of the mendeleev's modules. +Here you'll find API documentation of the mendeleev's modules. For most users it'll be enough to use the high-level API provided by the classes below. +For more advances use cases you can use the lower-level functions and classes across the modules. +.. toctree:: + :maxdepth: 2 + + Models + + +Modules +======= .. autosummary:: :toctree: - mendeleev.db mendeleev.cli + mendeleev.db mendeleev.econf mendeleev.electronegativity mendeleev.fetch mendeleev.mendeleev - mendeleev.models - mendeleev.ion + mendeleev.utils + + +Visualization +============= + +The main entry point for visualizing periodic tables with different +properties is the :func:`mendeleev.vis.periodictable.periodic_table` function. + +.. toctree:: + mendeleev.vis.periodictable mendeleev.vis.bokeh mendeleev.vis.plotly mendeleev.vis.seaborn - mendeleev.vis.utils - mendeleev.utils + mendeleev.vis.utils \ No newline at end of file diff --git a/docs/source/api/electronegativity.rst b/docs/source/api/electronegativity.rst deleted file mode 100644 index 870e7936..00000000 --- a/docs/source/api/electronegativity.rst +++ /dev/null @@ -1,7 +0,0 @@ -.. currentmodule:: mendeleev.electronegativity - -Electronegativity module -======================== - -.. automodule:: mendeleev.electronegativity - :members: diff --git a/docs/source/api/mendeleev.cli.rst b/docs/source/api/mendeleev.cli.rst index aceb6048..caccff92 100644 --- a/docs/source/api/mendeleev.cli.rst +++ b/docs/source/api/mendeleev.cli.rst @@ -1,6 +1,29 @@ mendeleev.cli ============= -.. currentmodule:: mendeleev +.. automodule:: mendeleev.cli + + + + + + + + .. rubric:: Functions + + .. autosummary:: + + clielement + + + + + + + + + + + + -.. autodata:: cli \ No newline at end of file diff --git a/docs/source/api/mendeleev.ion.rst b/docs/source/api/mendeleev.ion.rst deleted file mode 100644 index 2dfca057..00000000 --- a/docs/source/api/mendeleev.ion.rst +++ /dev/null @@ -1,6 +0,0 @@ -mendeleev.ion -============= - -.. currentmodule:: mendeleev - -.. autodata:: ion \ No newline at end of file diff --git a/docs/source/api/mendeleev.models.rst b/docs/source/api/mendeleev.models.rst deleted file mode 100644 index b5d55f51..00000000 --- a/docs/source/api/mendeleev.models.rst +++ /dev/null @@ -1,48 +0,0 @@ -mendeleev.models -================ - -.. automodule:: mendeleev.models - - - - - - - - .. rubric:: Functions - - .. autosummary:: - - estimate_from_group - fetch_attrs_for_group - with_uncertainty - - - - - - .. rubric:: Classes - - .. autosummary:: - - Element - Group - IonicRadius - IonizationEnergy - Isotope - IsotopeDecayMode - OxidationState - PhaseTransition - PropertyMetadata - ScreeningConstant - Series - ValueOrigin - - - - - - - - - diff --git a/docs/source/api/mendeleev.utils.rst b/docs/source/api/mendeleev.utils.rst index 18d5542c..dde1e151 100644 --- a/docs/source/api/mendeleev.utils.rst +++ b/docs/source/api/mendeleev.utils.rst @@ -13,8 +13,10 @@ .. autosummary:: + apply_rst_format coeffs n_effective + render_rst_table diff --git a/docs/source/api/mendeleev.vis.bokeh.rst b/docs/source/api/mendeleev.vis.bokeh.rst index ca3aad6c..ce9666c2 100644 --- a/docs/source/api/mendeleev.vis.bokeh.rst +++ b/docs/source/api/mendeleev.vis.bokeh.rst @@ -3,27 +3,9 @@ mendeleev.vis.bokeh .. automodule:: mendeleev.vis.bokeh - - - - - .. rubric:: Functions - .. autosummary:: - - periodic_table_bokeh - - - + .. autofunction:: periodic_table_bokeh - - - - - - - - diff --git a/docs/source/api/mendeleev.vis.periodictable.rst b/docs/source/api/mendeleev.vis.periodictable.rst index a13b5430..cb3e3752 100644 --- a/docs/source/api/mendeleev.vis.periodictable.rst +++ b/docs/source/api/mendeleev.vis.periodictable.rst @@ -1,29 +1,10 @@ -mendeleev.vis.periodictable +mendeleev.vis.periodictable =========================== .. automodule:: mendeleev.vis.periodictable - - - - - - .. rubric:: Functions - .. autosummary:: - - periodic_table - - - - - - - + .. autofunction:: periodic_table - - - - diff --git a/docs/source/api/mendeleev.vis.plotly.rst b/docs/source/api/mendeleev.vis.plotly.rst index c0a92c2a..204a233b 100644 --- a/docs/source/api/mendeleev.vis.plotly.rst +++ b/docs/source/api/mendeleev.vis.plotly.rst @@ -3,29 +3,11 @@ mendeleev.vis.plotly .. automodule:: mendeleev.vis.plotly - - - - - .. rubric:: Functions - .. autosummary:: - - create_annotation - create_tile - periodic_table_plotly - - - + .. autofunction:: periodic_table_plotly + .. autofunction:: create_annotation - - - - - - - - + .. autofunction:: create_tile diff --git a/docs/source/api/mendeleev.vis.rst b/docs/source/api/mendeleev.vis.rst deleted file mode 100644 index c0258458..00000000 --- a/docs/source/api/mendeleev.vis.rst +++ /dev/null @@ -1,35 +0,0 @@ -mendeleev.vis -============= - -.. automodule:: mendeleev.vis - - - - - - - - - - - - - - - - - - - -.. rubric:: Modules - -.. autosummary:: - :toctree: - :recursive: - - mendeleev.vis.bokeh - mendeleev.vis.periodictable - mendeleev.vis.plotly - mendeleev.vis.seaborn - mendeleev.vis.utils - diff --git a/docs/source/api/mendeleev.vis.seaborn.rst b/docs/source/api/mendeleev.vis.seaborn.rst index 86ab514e..ba6555d1 100644 --- a/docs/source/api/mendeleev.vis.seaborn.rst +++ b/docs/source/api/mendeleev.vis.seaborn.rst @@ -3,27 +3,9 @@ mendeleev.vis.seaborn .. automodule:: mendeleev.vis.seaborn - - - - - .. rubric:: Functions - .. autosummary:: - - heatmap - - - - - - - - - - - + .. autofunction:: heatmap diff --git a/docs/source/api/mendeleev.vis.utils.rst b/docs/source/api/mendeleev.vis.utils.rst index 3ace46a2..1cc796e7 100644 --- a/docs/source/api/mendeleev.vis.utils.rst +++ b/docs/source/api/mendeleev.vis.utils.rst @@ -3,29 +3,11 @@ mendeleev.vis.utils .. automodule:: mendeleev.vis.utils - - - - - .. rubric:: Functions - .. autosummary:: - - add_tile_coordinates - colormap_column - create_vis_dataframe - - - - - - - - - - - + .. autofunction:: add_tile_coordinates + .. autofunction:: colormap_column + .. autofunction:: create_vis_dataframe diff --git a/docs/source/api/models.rst b/docs/source/api/models.rst index 0ba2fc90..7fdeb010 100644 --- a/docs/source/api/models.rst +++ b/docs/source/api/models.rst @@ -13,6 +13,27 @@ Element .. autoclass:: mendeleev.models.Element :members: +.. _econf-class: + +ElectronicConfiguration +----------------------- + +.. currentmodule:: mendeleev.econf + +.. autoclass:: mendeleev.econf.ElectronicConfiguration + :members: + + +.. _group-class: + +Group +----- + +.. currentmodule:: mendeleev.models + +.. autoclass:: mendeleev.models.Group + :members: + .. _ion-class: @@ -55,6 +76,27 @@ Isotope .. autoclass:: mendeleev.models.Isotope :members: + +.. _oxidationstate-class: + +OxidationState +-------------- + +.. currentmodule:: mendeleev.models + +.. autoclass:: mendeleev.models.OxidationState + :members: + +.. _scatteringfactor-class: + +ScatteringFactor +---------------- + +.. currentmodule:: mendeleev.models + +.. autoclass:: mendeleev.models.ScatteringFactor + :members: + .. _screeningconstant-class: ScreeningConstant @@ -75,26 +117,18 @@ Series .. autoclass:: mendeleev.models.Series :members: -.. _group-class: - -Group ------ - -.. currentmodule:: mendeleev.models -.. autoclass:: mendeleev.models.Group - :members: +.. _phasetransition-class: -.. _oxidationstate-class: - -OxidationState --------------- +PhaseTransition +--------------- .. currentmodule:: mendeleev.models -.. autoclass:: mendeleev.models.OxidationState +.. autoclass:: mendeleev.models.PhaseTransition :members: + .. _propertymetadata-class: PropertyMetadata @@ -105,13 +139,3 @@ PropertyMetadata .. autoclass:: mendeleev.models.PropertyMetadata :members: -.. _econf-class: - -ElectronicConfiguration ------------------------ - -.. currentmodule:: mendeleev.econf - -.. autoclass:: mendeleev.econf.ElectronicConfiguration - :members: - diff --git a/docs/source/api/utils.rst b/docs/source/api/utils.rst deleted file mode 100644 index df59b200..00000000 --- a/docs/source/api/utils.rst +++ /dev/null @@ -1,5 +0,0 @@ -utils module -============ - -.. automodule:: mendeleev.utils - :members: \ No newline at end of file diff --git a/docs/source/api/vis.rst b/docs/source/api/vis.rst deleted file mode 100644 index 2a2e64fa..00000000 --- a/docs/source/api/vis.rst +++ /dev/null @@ -1,38 +0,0 @@ -.. currentmodule:: mendeleev.vis -.. _vis: - -Visualization module -==================== - -Periodic table visualizations ------------------------------ - -The main entry point for visualizing periodic tables with different -properties is the :func:`periodictable.periodic_table` function. - -.. automodule:: mendeleev.vis.periodictable - :members: - -bokeh ------ - -.. automodule:: mendeleev.vis.bokeh - :members: - -plotly ------- - -.. automodule:: mendeleev.vis.plotly - :members: - -seaborn -------- - -.. automodule:: mendeleev.vis.seaborn - :members: - -utils ------ - -.. automodule:: mendeleev.vis.utils - :members: diff --git a/mendeleev/cli.py b/mendeleev/cli.py index 8e0d4d9e..9aa71e3d 100644 --- a/mendeleev/cli.py +++ b/mendeleev/cli.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- -from __future__ import print_function +"""Module defining the command line interface for mendeleev.""" import argparse import textwrap diff --git a/mendeleev/db.py b/mendeleev/db.py index b2ce8831..72876f62 100644 --- a/mendeleev/db.py +++ b/mendeleev/db.py @@ -1,3 +1,5 @@ +"""Low-level database access functions.""" + import os from sqlalchemy import create_engine diff --git a/mendeleev/fetch.py b/mendeleev/fetch.py index 6a63a173..a7932907 100644 --- a/mendeleev/fetch.py +++ b/mendeleev/fetch.py @@ -1,3 +1,5 @@ +"""Utility functions to fetch data from the database in bulk""" + from typing import List, Union import pandas as pd diff --git a/mendeleev/ion.py b/mendeleev/ion.py index d9545502..8d60f1f9 100644 --- a/mendeleev/ion.py +++ b/mendeleev/ion.py @@ -1,3 +1,5 @@ +"""Module defining the database models for ions.""" + from statistics import mean from typing import List from mendeleev import element diff --git a/mendeleev/mendeleev.py b/mendeleev/mendeleev.py index 2a41db76..0b254155 100644 --- a/mendeleev/mendeleev.py +++ b/mendeleev/mendeleev.py @@ -1,4 +1,4 @@ -# -*- coding: utf-8 -*- +"""Entry point for the Mendeleev package for instantiating elements and isotopes.""" from typing import List, Union diff --git a/mendeleev/models.py b/mendeleev/models.py index 471c4495..c0634dd8 100644 --- a/mendeleev/models.py +++ b/mendeleev/models.py @@ -1,6 +1,6 @@ # -*- coding: utf-8 -*- -"""module defining the database models""" +"""Module defining the database models for elements and related properties.""" from typing import Any, Callable, Dict, List, Tuple, Union from operator import attrgetter @@ -31,13 +31,17 @@ __all__ = [ "Element", - "IonizationEnergy", + "Group", "IonicRadius", - "OxidationState", + "IonizationEnergy", "Isotope", + "IsotopeDecayMode", + "OxidationState", + "PhaseTransition", "PropertyMetadata", - "Series", + "ScatteringFactor", "ScreeningConstant", + "Series", ] @@ -1164,6 +1168,7 @@ class PhaseTransition(Base): critical_pressure (float): Critical pressure in MPa triple_point_temperature (float): Temperature in K of the triple point triple_point_pressure (float): Pressure in kPa of the triple point + alotrope (str): Allotrope """ __tablename__ = "phasetransitions" diff --git a/mendeleev/utils.py b/mendeleev/utils.py index 7971d7cc..ab895f8d 100644 --- a/mendeleev/utils.py +++ b/mendeleev/utils.py @@ -1,3 +1,5 @@ +"""Utility functions for Mendeleev package.""" + from typing import Union, Tuple import math