From 0a1b274bd446a5da7be2daa62f1f53c54d08930f Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Mon, 28 Oct 2024 14:19:10 +0000 Subject: [PATCH 1/7] Added hoveref as a sphinx extension --- docs/source/conf.py | 1 + poetry.lock | 23 +++++++++++++++++++++-- pyproject.toml | 1 + 3 files changed, 23 insertions(+), 2 deletions(-) diff --git a/docs/source/conf.py b/docs/source/conf.py index 31d58d942..cfb62c172 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -100,6 +100,7 @@ "sphinx_rtd_theme", "sphinx_external_toc", "sphinx_design", + "hoverxref.extension", ] autodoc_default_flags = ["members"] autosummary_generate = True diff --git a/poetry.lock b/poetry.lock index 8c4507e46..a5e8b1211 100644 --- a/poetry.lock +++ b/poetry.lock @@ -1,4 +1,4 @@ -# This file is automatically @generated by Poetry 1.8.3 and should not be changed by hand. +# This file is automatically @generated by Poetry 1.8.2 and should not be changed by hand. [[package]] name = "alabaster" @@ -3929,6 +3929,25 @@ code-style = ["pre-commit (>=2.12)"] rtd = ["myst-parser (>=1.0.0)", "sphinx-book-theme (>=1.0.0)"] testing = ["coverage", "pytest (>=7.1)", "pytest-cov", "pytest-regressions"] +[[package]] +name = "sphinx-hoverxref" +version = "1.4.1" +description = "Sphinx extension to show tooltips with content embedded when hover a reference." +optional = false +python-versions = "*" +files = [ + {file = "sphinx_hoverxref-1.4.1-py2.py3-none-any.whl", hash = "sha256:be4c8afecf4d6f9b1ecccafd7be736fd8a761c9ab2db36140ca1ee40196916a8"}, + {file = "sphinx_hoverxref-1.4.1.tar.gz", hash = "sha256:b5e302ff5ca953ca3f271d9b9f09d92f59158335dfa8e9cfac415d1686a3f27b"}, +] + +[package.dependencies] +sphinx = ">=5.0" +sphinxcontrib-jquery = "*" + +[package.extras] +doc = ["sphinx", "sphinx-autoapi", "sphinx-autobuild", "sphinx-notfound-page", "sphinx-prompt", "sphinx-rtd-theme", "sphinx-tabs", "sphinx-version-warning", "sphinxcontrib-bibtex (>=2.6.0)", "sphinxemoji"] +test = ["tox"] + [[package]] name = "sphinx-rtd-theme" version = "3.0.1" @@ -4562,4 +4581,4 @@ type = ["pytest-mypy"] [metadata] lock-version = "2.0" python-versions = ">=3.10,<3.13" -content-hash = "1d8a04b2c4c21608fc5359b45d56ee1f070d44405a9147457e6dfc424bcda8bb" +content-hash = "21305adcb8b8c5828870cf3c2df159ae33cc4d628bc0b6261d491006eaabdc33" diff --git a/pyproject.toml b/pyproject.toml index c1b3351a1..14295d223 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -80,6 +80,7 @@ sphinx-external-toc = "^1.0.0" sphinx-rtd-theme = ">=2,<4" sphinxcontrib-bibtex = "^2.6.1" sphinxcontrib-mermaid = ">=0.9.2,<1.1.0" +sphinx-hoverxref = "^1.4.1" [build-system] build-backend = "poetry.core.masonry.api" From 2d49b2d6b6e39347d87ce4132eb6e934c0484fb9 Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Wed, 8 Jan 2025 09:17:58 +0000 Subject: [PATCH 2/7] Added a glossary for soil pool abbreviations --- .../theory/soil/soil_glossary.md | 35 +++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/source/virtual_ecosystem/theory/soil/soil_glossary.md diff --git a/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md b/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md new file mode 100644 index 000000000..43b40e62f --- /dev/null +++ b/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md @@ -0,0 +1,35 @@ +--- +jupyter: + jupytext: + cell_metadata_filter: all,-trusted + main_language: python + notebook_metadata_filter: settings,mystnb,language_info + text_representation: + extension: .md + format_name: markdown + format_version: '1.3' + jupytext_version: 1.16.6 +--- + +# Soil pool abbreviations + +.. glossary:: + + POM + Particulate Organic Matter. A form of organic matter that derives from the + decomposition and fragmentation of litter and other necromass. Generally, these + particulates are still in a state where the tissue they orginated from can be + determined. This chemical complexity makes this a form of protected carbon, however + this is generally only a signifcant store of protected carbon in heavily waterlogged + soils. + + MAOM + Mineral Associated Organic Matter. This is organic matter which has formed a strong + association with soil minerals. This association impedes breakdown, making this a + form of protected carbon. + + LMWC + Low Molecular Weight Carbon. These are organic molecules that are simple and + soluble, i.e. molecules that do not require further transformation to be + transportable across cell membranes. Thus, the avaliablity of this type of organic + matter strongly determines microbial growth rates. From 02ee9da2d49c5d394a745f144ecb0343dd726bd3 Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Wed, 8 Jan 2025 09:47:58 +0000 Subject: [PATCH 3/7] Fixed problems with the soil abbreviation glossary --- docs/source/_toc.yaml | 1 + .../theory/soil/soil_glossary.md | 37 ++++++++++--------- 2 files changed, 20 insertions(+), 18 deletions(-) diff --git a/docs/source/_toc.yaml b/docs/source/_toc.yaml index 000cc5b87..43f66f954 100644 --- a/docs/source/_toc.yaml +++ b/docs/source/_toc.yaml @@ -17,6 +17,7 @@ subtrees: - file: virtual_ecosystem/theory/soil/soil_theory - file: virtual_ecosystem/theory/soil/litter_theory - file: virtual_ecosystem/theory/soil/environmental_links + - file: virtual_ecosystem/theory/soil/soil_glossary - file: virtual_ecosystem/theory/animals/animal_theory entries: - file: virtual_ecosystem/theory/animals/carcasses_and_excrement diff --git a/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md b/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md index 43b40e62f..48ff0876c 100644 --- a/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md +++ b/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md @@ -11,25 +11,26 @@ jupyter: jupytext_version: 1.16.6 --- -# Soil pool abbreviations +# Abbreviations -.. glossary:: +```{glossary} - POM - Particulate Organic Matter. A form of organic matter that derives from the - decomposition and fragmentation of litter and other necromass. Generally, these - particulates are still in a state where the tissue they orginated from can be - determined. This chemical complexity makes this a form of protected carbon, however - this is generally only a signifcant store of protected carbon in heavily waterlogged - soils. +POM + Particulate Organic Matter. A form of organic matter that derives from the + decomposition and fragmentation of litter and other necromass. Generally, these + particulates are still in a state where the tissue they orginated from can be + determined. This chemical complexity makes this a form of protected carbon, however this + is generally only a signifcant store of protected carbon in heavily waterlogged soils. - MAOM - Mineral Associated Organic Matter. This is organic matter which has formed a strong - association with soil minerals. This association impedes breakdown, making this a - form of protected carbon. +MAOM + Mineral Associated Organic Matter. This is organic matter which has formed a strong + association with soil minerals. This association impedes breakdown, making this a form + of protected carbon. - LMWC - Low Molecular Weight Carbon. These are organic molecules that are simple and - soluble, i.e. molecules that do not require further transformation to be - transportable across cell membranes. Thus, the avaliablity of this type of organic - matter strongly determines microbial growth rates. +LMWC + Low Molecular Weight Carbon. These are organic molecules that are simple and soluble, + i.e. molecules that do not require further transformation to be transportable across + cell membranes. Thus, the avaliablity of this type of organic matter strongly determines + microbial growth rates. + +``` From 513a9d4b5f51080ba4027f3adfeb07f718dda73a Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Wed, 8 Jan 2025 09:59:21 +0000 Subject: [PATCH 4/7] Added glossary links to soil theory markdown file --- .../virtual_ecosystem/theory/soil/soil_theory.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/source/virtual_ecosystem/theory/soil/soil_theory.md b/docs/source/virtual_ecosystem/theory/soil/soil_theory.md index 1230e12ff..4e188c225 100644 --- a/docs/source/virtual_ecosystem/theory/soil/soil_theory.md +++ b/docs/source/virtual_ecosystem/theory/soil/soil_theory.md @@ -90,14 +90,14 @@ very slowly (order of years to decades) and so in most soils it is the main form Microbial biomass accounts for a small fraction of total soil carbon. However, microbes are key drivers of soil carbon cycling, with significant flows of carbon through the -microbial biomass pool. Microbes assist in the formation of LMWC by excreting enzymes -that breakdown POM. They then utilise LMWC to form biomass. Microbial waste products and -necromass either break down into LMWC, or form mineral associations. In addition, -microbial respiration is one of the major sources of carbon loss to the system. This -pool turns over rapidly (order of days) and only represents a very small fraction of -total soil carbon. However, it is very important to track because many soil processes -are driven by microbes, and so depend either implicitly or explicitly on the size of -this pool. +microbial biomass pool. Microbes assist in the formation of {term}`LMWC` by excreting +enzymes that breakdown {term}`POM`. They then utilise LMWC to form biomass. Microbial +waste products and necromass either break down into LMWC, or form mineral associations. +In addition, microbial respiration is one of the major sources of carbon loss to the +system. This pool turns over rapidly (order of days) and only represents a very small +fraction of total soil carbon. However, it is very important to track because many soil +processes are driven by microbes, and so depend either implicitly or explicitly on the +size of this pool. ## Nitrogen pools From bbf88fbb25d27cd64774158a5750b7edccf7599b Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Wed, 8 Jan 2025 10:08:29 +0000 Subject: [PATCH 5/7] Added abbreviation links into some of the soil pool docstrings --- virtual_ecosystem/models/soil/pools.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/virtual_ecosystem/models/soil/pools.py b/virtual_ecosystem/models/soil/pools.py index baa3def1f..947345b7c 100644 --- a/virtual_ecosystem/models/soil/pools.py +++ b/virtual_ecosystem/models/soil/pools.py @@ -305,7 +305,7 @@ def calculate_microbial_changes( ): """Calculate the changes for the microbial biomass and enzyme pools. - This function calculates the uptake of low molecular weight carbon by the microbial + This function calculates the uptake of :term:`LMWC` by the microbial biomass pool and uses this to calculate the net change in the pool. The net change in each enzyme pool is found, and finally the total rate at which necromass is created is found. @@ -395,8 +395,7 @@ def calculate_enzyme_mediated_rates( Returns: A dataclass containing the enzyme mediated decomposition rates of both the - particulate organic matter (POM) and mineral associated organic matter (MAOM) - pool. + :term:`POM` and :term:`MAOM` pool. """ pom_decomposition_to_lmwc = calculate_enzyme_mediated_decomposition( From dfa474b165b4d13aa7ad723c42be4218e7a52352 Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Wed, 8 Jan 2025 10:21:49 +0000 Subject: [PATCH 6/7] Setup glossary items to display as tooltips --- docs/source/conf.py | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/source/conf.py b/docs/source/conf.py index cfb62c172..631adfda9 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -246,3 +246,8 @@ class MyReferenceStyle(AuthorYearReferenceStyle): html_sidebars = { "**": ["logo-text.html", "globaltoc.html", "localtoc.html", "searchbox.html"] } + +# Configure hoverxref +hoverxref_roles = ["term"] + +hoverxref_role_types = {"term": "tooltip"} From fcc129f5dda1a2c4777738261150921c47175b8b Mon Sep 17 00:00:00 2001 From: Jacob Cook Date: Wed, 8 Jan 2025 15:50:54 +0000 Subject: [PATCH 7/7] Replaced soil specific glossary with a general project glossary --- docs/source/_toc.yaml | 2 +- .../theory/soil/soil_glossary.md => glossary.md} | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) rename docs/source/{virtual_ecosystem/theory/soil/soil_glossary.md => glossary.md} (98%) diff --git a/docs/source/_toc.yaml b/docs/source/_toc.yaml index 43f66f954..d672d03dd 100644 --- a/docs/source/_toc.yaml +++ b/docs/source/_toc.yaml @@ -17,7 +17,6 @@ subtrees: - file: virtual_ecosystem/theory/soil/soil_theory - file: virtual_ecosystem/theory/soil/litter_theory - file: virtual_ecosystem/theory/soil/environmental_links - - file: virtual_ecosystem/theory/soil/soil_glossary - file: virtual_ecosystem/theory/animals/animal_theory entries: - file: virtual_ecosystem/theory/animals/carcasses_and_excrement @@ -215,6 +214,7 @@ subtrees: - caption: Reference entries: + - file: glossary - file: bibliography - file: genindex - file: modindex diff --git a/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md b/docs/source/glossary.md similarity index 98% rename from docs/source/virtual_ecosystem/theory/soil/soil_glossary.md rename to docs/source/glossary.md index 48ff0876c..db4815799 100644 --- a/docs/source/virtual_ecosystem/theory/soil/soil_glossary.md +++ b/docs/source/glossary.md @@ -11,7 +11,7 @@ jupyter: jupytext_version: 1.16.6 --- -# Abbreviations +# Glossary ```{glossary}