Set up bibliography

requirements.txt

@@ -1,3 +1,4 @@
 sphinx
 sphinx_rtd_theme >= 0.4.3
+sphinxcontrib-bibtex
 zest.releaser

source/conf.py

@@ -1,7 +1,17 @@
 #!/usr/bin/env python3
+from dataclasses import dataclass, field
+
 import datetime
 import sphinx_rtd_theme
 
+from pybtex.style.formatting.alpha import Style as AlphaStyle
+from pybtex.style.labels.alpha import LabelStyle as AlphaLabelStyle
+from pybtex.style.labels import BaseLabelStyle
+from pybtex.plugin import register_plugin
+import sphinxcontrib.bibtex.plugin
+from sphinxcontrib.bibtex.style.referencing import BracketStyle
+from sphinxcontrib.bibtex.style.referencing.author_year import AuthorYearReferenceStyle
+
 # The 3Di release name that's shown at the top of the sidebar.
 # Note: non-production documentation builds are marked as such, you don't need
 # to change the release name for that.
@@ -19,7 +29,44 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-extensions = ["sphinx.ext.todo"]
+extensions = ["sphinx.ext.todo", "sphinxcontrib.bibtex"]
+
+# bibtex (bibliography extension)
+## Format references as "Author (year)"
+def bracket_style() -> BracketStyle:
+    return BracketStyle(
+        left='(',
+        right=')',
+    )
+
+@dataclass
+class AuthorYearRoundReferenceStyle(AuthorYearReferenceStyle):
+    bracket_parenthetical: BracketStyle = field(default_factory=bracket_style)
+    bracket_textual: BracketStyle = field(default_factory=bracket_style)
+    bracket_author: BracketStyle = field(default_factory=bracket_style)
+    bracket_label: BracketStyle = field(default_factory=bracket_style)
+    bracket_year: BracketStyle = field(default_factory=bracket_style)
+
+
+sphinxcontrib.bibtex.plugin.register_plugin(
+    'sphinxcontrib.bibtex.style.referencing',
+    'author_year_round', AuthorYearRoundReferenceStyle)
+
+## Format labels in bibliography
+class CustomLabelStyle(AlphaLabelStyle):
+    def format_label(self, entry):
+        return f"{entry.persons['author'][0].last_names[0]} {entry.fields['year']}"
+
+
+class CustomStyle(AlphaStyle):
+    default_label_style = 'custom'
+
+
+register_plugin('pybtex.style.labels', 'custom', CustomLabelStyle)
+register_plugin('pybtex.style.formatting', 'customstyle', CustomStyle)
+
+bibtex_bibfiles = ['literature.bib']
+bibtex_reference_style = 'author_year_round'
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

source/index.rst

@@ -33,6 +33,8 @@ If you are interested in a **product demo**, a **live** or **online training**,
 The computational core is developed by Prof. dr. ir. G. S. Stelling, who worked on the subgrid technique in close collaboration with Prof. dr. ir. V. Casulli.
 Most of the techniques used within the 3Di computational core are published in scientific papers. The rest of the software is maintained and developed by Nelen & Schuurmans Technology.
 
+:cite:t:`Volp2013`
+
 Table of contents
 =================
 
@@ -86,3 +88,9 @@ Table of contents
 
    a_releasenotes
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Literature
+   :name: Literature
+
+   l_literature

source/l_literature.rst

@@ -0,0 +1,6 @@
+Literature
+==========
+
+.. bibliography:: literature.bib
+   :all:
+   :style: customstyle

source/literature.bib

@@ -0,0 +1,32 @@
+@article{VargasLuna2015,
+   abstract = {The presence of vegetation modifies flow and sediment transport in alluvial channels and hence the morphological evolution of river systems. Plants increase the local roughness, modify flow patterns and provide additional drag, decreasing the bed-shear stress and enhancing local sediment deposition. For this, it is important to take into account the presence of vegetation in morphodynamic modelling. Models describing the effects of vegetation on water flow and sediment transport already exist, but comparative analyses and validations on extensive datasets are still lacking. In order to provide practical information for modelling purposes, we analysed the performance of a large number of models on flow resistance, vegetation drag, vertical velocity profiles and bed-shear stresses in vegetated channels. Their assessments and applicability ranges are derived by comparing their predictions with measured values from a large dataset for different types of submerged and emergent vegetation gathered from the literature. The work includes assessing the performance of the sediment transport capacity formulae of Engelund and Hansen and van Rijn in the case of vegetated beds, as well as the value of the drag coefficient to be used for different types of vegetation and hydraulic conditions. The results provide a unique comparative overview of existing models for the assessment of the effects of vegetation on morphodynamics, highlighting their performances and applicability ranges.},
+   author = {Andrés Vargas-Luna and Alessandra Crosato and Wim S.J. Uijttewaal},
+   doi = {10.1002/ESP.3633},
+   issn = {1096-9837},
+   issue = {2},
+   journal = {Earth Surface Processes and Landforms},
+   keywords = {flow resistance,modelling,morphodynamics,sediment transport,vegetation},
+   month = {2},
+   pages = {157-176},
+   publisher = {John Wiley & Sons, Ltd},
+   title = {Effects of vegetation on flow and sediment transport: comparative analyses and validation of predicting models},
+   volume = {40},
+   url = {https://onlinelibrary.wiley.com/doi/full/10.1002/esp.3633 https://onlinelibrary.wiley.com/doi/abs/10.1002/esp.3633 https://onlinelibrary.wiley.com/doi/10.1002/esp.3633},
+   year = {2015},
+}
+@article{Volp2013,
+   abstract = {This study presents a finite volume hydrodynamic model for shallow water flow that computes on a coarse grid, but accounts for high-resolution bathymetry and roughness variations on a subgrid. The detailed information can be incorporated by using the assumption of a uniform flow direction and a uniform friction slope within a part of a coarse-grid cell. It is shown in two examples that the results of coarse-grid simulations become as good as high-resolution results, but at much lower computational cost. © 2013. American Geophysical Union. All Rights Reserved.},
+   author = {N. D. Volp and B. C. Van Prooijen and G. S. Stelling},
+   doi = {10.1002/WRCR.20324},
+   issn = {1944-7973},
+   issue = {7},
+   journal = {Water Resources Research},
+   keywords = {computational fluid dynamics,effective depth,friction depth,salt marsh,shallow water equations,subgrid},
+   month = {7},
+   pages = {4126-4135},
+   publisher = {John Wiley & Sons, Ltd},
+   title = {A finite volume approach for shallow water flow accounting for high-resolution bathymetry and roughness data},
+   volume = {49},
+   url = {https://onlinelibrary.wiley.com/doi/full/10.1002/wrcr.20324 https://onlinelibrary.wiley.com/doi/abs/10.1002/wrcr.20324 https://agupubs.onlinelibrary.wiley.com/doi/10.1002/wrcr.20324},
+   year = {2013},
+}