diff --git a/doc/_static/custom.css b/doc/_static/custom.css new file mode 100644 index 00000000..d48a159b --- /dev/null +++ b/doc/_static/custom.css @@ -0,0 +1,216 @@ +/* Hero */ + + +#hero { + display: flex; + flex-direction: row; + min-height: min(calc(75vh), 1000px); /* Make hero fill up most of the page on load */ +} +#hero-left { + max-width: 476px; + width: 40%; + margin: auto 0; +} +#hero-right { + min-width: 476px; + width: 60%; + margin: auto 0; +} + +.homepage-button-container { + margin-bottom: 1rem; + display: flex; + flex-direction: column; +} +.homepage-button-container-row { + display: flex; + flex-wrap: wrap; +} + +.homepage-button-container a { + transition: 0.1s; +} +.homepage-button { + min-width: 142px; + padding: 0.5em 2em; + border: 1px solid var(--pst-color-primary); + border-radius: 4px; + margin: 1em 0.5em 0.5em 0; +} +.primary-button { + background-color: var(--pst-color-primary); + color: var(--pst-color-background) !important; +} +.secondary-button { + background-color: var(--pst-color-background); + color: var(--pst-color-primary); +} +.homepage-button:hover { + text-decoration: none; + background-color: var(--pst-color-secondary); + color: var(--pst-color-background); + border: 1px solid var(--pst-color-secondary); +} +.homepage-button-link { + text-decoration: underline; +} + +/* Key Features */ +#key-features .sd-card-body { + display: flex; +} +#key-features .sd-card img { + width: 140px; + height: 140px; +} +#key-features .sd-card-body .key-features-text { + min-width: 70%; + padding: 20px 10px; +} + +/* Sponsors */ +#sponsors-and-institutional-partners p { + text-align: center; +} +#sponsors-and-institutional-partners img { + max-width: 200px; +} + +/* Support ArviZ */ +#support-arviz .sd-col { + margin-bottom: 3rem; +} +#support-arviz p { + text-align: center; +} +.support-arviz-img-merch img { + height: 160px; +} +.support-arviz-img-donate img { + display: block; + width: 100%; + padding: 60px 40px 20px; +} +.support-arviz-img-donate-responsive img { + display: none; + margin: auto; + width: 80%; + min-width: 0px; + padding: 20px; +} + +/* Responsive */ +@media (max-width: 768px) { + #hero { + display: block; + } + #hero-left, + #hero-right { + width: 100%; + min-width: 0px; + } + .support-arviz-img-donate img { + display: none; + } + .support-arviz-img-donate-responsive img { + display: block; + } +} + +/* -------------------- HOMEPAGE + EXAMPLE GALLERY -------------------- */ + +/* Homepage - grid layout */ +.home-flex-grid { + display: flex; + flex-flow: row wrap; + justify-content: center; + gap: 10px; + padding: 20px 0px 40px; +} + +/* Homepage + Example Gallery Body - Set dimensions */ +.home-img-plot, +.bd-content div.sd-card.example-gallery .sd-card-body, +.home-img-plot-overlay, +.example-img-plot-overlay { + display: flex; + justify-content: center; + align-items: center; + overflow: hidden; + padding: 10px; +} +.home-img-plot, +.home-img-plot-overlay { + width: 235px; + height: 130px; +} +.bd-content div.sd-card.example-gallery .sd-card-body, +.example-img-plot-overlay { + width: 100%; + height: 150px; +} +.home-img-plot img, +.bd-content div.sd-card.example-gallery .sd-card-body img { + /* Images keep aspect ratio and fit in container */ + /* To make images stretch/fill container, change to min-width */ + max-width: 100%; + max-height: 100%; +} + +/* Homepage + Example Gallery Body - Set color and hover */ +.home-img-plot.img-thumbnail, +.bd-content div.sd-card.example-gallery .sd-card-body { + background-color: var(--pst-color-plot-background); /* Same as img-thumbnail from pydata css, adjusted for dark mode */ +} +.home-img-plot-overlay, +.example-img-plot-overlay, +.bd-content div.sd-card.example-gallery .sd-card-body { + border: 1px solid #dee2e6; /* Same as img-thumbnail from pydata css */ + border-radius: 0.25rem; /* Same as img-thumbnail from pydata css */ +} +.home-img-plot-overlay, +.example-img-plot-overlay, +.example-img-plot-overlay p.sd-card-text { + background: var(--pst-color-primary); + position: absolute; + color: var(--pst-color-background); + opacity: 0; + transition: .2s ease; + text-align: center; + padding: 10px; + z-index: 998; /* Make sure overlay is above image...this is here to handle dark mode */ +} +.home-img-plot-overlay:hover, +.bd-content div.sd-card.example-gallery:hover .example-img-plot-overlay, +.example-img-plot-overlay p.sd-card-text { + opacity: 90%; +} + +/* Example Gallery Body - Set syntax highlighting for code on hover */ +.example-img-plot-overlay .sd-card-text code.code { + background-color: var(--pst-color-background); +} +.example-img-plot-overlay .sd-card-text .code span.pre { + color: var(--pst-color-primary); + font-weight: 700; +} + +/* Example Gallery Footer - Plot titles goes here */ +.example-gallery .sd-card-footer { + height: 40px; + padding: 5px; + border-top: none !important; +} +.example-gallery .sd-card-footer p.sd-card-text { + color: var(--pst-color-text-muted); + font-size: 1rem; /* This is font size for plot titles (below the chart) */ + font-weight: 700; +} +.sd-card.example-gallery:hover .sd-card-footer p.sd-card-text { + color: var(--pst-color-primary); /* Change text color on hover over card */ +} + +/* Overlapping */ +.example-gallery a.sd-stretched-link.reference.external { + z-index: 999; /* Countermeasure where z-index = 998 */ +} diff --git a/doc/_static/theme_overrides.css b/doc/_static/theme_overrides.css index 83ca9fb8..3206cfd8 100644 --- a/doc/_static/theme_overrides.css +++ b/doc/_static/theme_overrides.css @@ -16,3 +16,10 @@ } } + +html[data-theme="dark"] { + /* tobac primary colors: #A2C2E5, #4D80BE, F6D94F*/ + --pst-color-primary: #4D80BE; + --pst-color-secondary: #F6D94F; +} + diff --git a/doc/conf.py b/doc/conf.py index 03e268f2..b03f342b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -20,13 +20,19 @@ "sphinx.ext.napoleon", "nbsphinx", "sphinx_gallery.load_style", + "myst_parser", + "sphinx_design", ] html_theme = "pydata_sphinx_theme" html_static_path = ["_static"] +html_css_files = ["custom.css", "theme_overrides.css"] + exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] +source_suffix = {".rst": "restructuredtext", ".md": "restructuredtext"} +myst_enable_extensions = ["colon_fence"] html_theme_options = { @@ -59,6 +65,7 @@ # Include our custom CSS (currently for special table config) def setup(app): app.add_css_file("theme_overrides.css") + app.add_css_file("custom.css") # This should include all modules used in tobac. These are dummy imports, diff --git a/doc/developer_guide/index.rst b/doc/developer_guide/index.rst index 7b30d53d..5b81a38e 100644 --- a/doc/developer_guide/index.rst +++ b/doc/developer_guide/index.rst @@ -1,3 +1,5 @@ +.. _Developer-Guide: + ############################## Contributing ############################## diff --git a/doc/index.md b/doc/index.md new file mode 100644 index 00000000..5b9ff26f --- /dev/null +++ b/doc/index.md @@ -0,0 +1,247 @@ +--- +html_theme.sidebar_secondary.remove: +sd_hide_title: true +--- + + + + +(homepage)= +# tobac - Tracking and Object-Based Analysis of Clouds + +
+ +
+

tobac

+

Tracking atmospheric phenomena with your data

+

tobac is a package that identifies, tracks, and can be used for object-based analysis of atmospheric phenomena in model, observational, and remote sensing datasets.

+ + +
+ +
+ +::::::{grid} 2 +:gutter: 3 + +:::::{grid-item-card} +:link: /examples/Example_OLR_Tracking_satellite/Example_OLR_Tracking_satellite.html +:shadow: none +:class-card: example-gallery + +:::{div} example-img-plot-overlay +Track precipitating clouds with radar reflectivity +::: + +:::{image} ./images/Figure_linking.png +::: +::::: + +:::::{grid-item-card} +:link: /examples/Example_OLR_Tracking_satellite +:shadow: none +:class-card: example-gallery + +:::{div} example-img-plot-overlay +Forest Plot with ESS using `plot_forest` +::: + +:::{image} ./images/Figure_linking.png +::: +::::: + +:::::{grid-item-card} +:link: /examples/Example_OLR_Tracking_satellite +:shadow: none +:class-card: example-gallery + +:::{div} example-img-plot-overlay +Dist Plot using `plot_dist` +::: + +:::{image} ./images/Figure_linking.png +::: +::::: + +:::::{grid-item-card} +:link: /examples/Example_OLR_Tracking_satellite +:shadow: none +:class-card: example-gallery + +:::{div} example-img-plot-overlay +Density Plot (Comparison) using `plot_density` +::: + +:::{image} ./images/Figure_linking.png +::: +::::: + +:::::: + + + +
+
+ + + +# Key Features + +:::::{grid} 1 1 2 2 +:gutter: 5 + +::::{grid-item-card} +:shadow: none +:class-card: sd-border-0 + +:::{image} getting_started/images/cross.png +::: + +:::{div} key-features-text +Data Agnostic
+_tobac_ identifies and tracks atmospheric phenomena across different variables and different input datasets. + +::: +:::: + +::::{grid-item-card} +:shadow: none +:class-card: sd-border-0 + +:::{image} getting_started/images/cross.png +::: + +:::{div} key-features-text +Tracking in 2D and 3D
+_tobac_ tracks features in 2D spatial datasets or in 3D spatial datasets. +::: +:::: + +::::{grid-item-card} +:shadow: none +:class-card: sd-border-0 + +:::{image} getting_started/images/cross.png +::: + +:::{div} key-features-text +Fast
+_tobac_ is fast to start using, and runs quickly, even on large datasets +::: +:::: + +::::{grid-item-card} +:shadow: none +:class-card: sd-border-0 + +:::{image} getting_started/images/cross.png +::: + +:::{div} key-features-text +Flexible
+_tobac_ allows you to set _physical_ values to answer your science question +::: +:::: + +::::{grid-item-card} +:shadow: none +:class-card: sd-border-0 + +:::{image} getting_started/images/cross.png +::: + +:::{div} key-features-text +Built for Open Data
+With xarray and pandas support, _tobac_ data can be saved to be FAIR and compliant with open science principles. +::: +:::: + +::::{grid-item-card} +:shadow: none +:class-card: sd-border-0 + +:::{image} getting_started/images/cross.png +::: + +:::{div} key-features-text +Strong Heritage
+Used in a variety of projects and peer-reviewed publications and backed by a diverse international team. +::: +:::: +::::: + + +# *tobac* Use and Development + +::::{grid} 1 1 2 2 + +:::{grid-item} + +

Contributions

+ +Contributions and issue reports are very welcome at +[the GitHub repository](https://github.com/tobac-project/tobac). +We have a {ref}`developer guide ` to help you through the process. We also offer mentoring for new contributors; see the {ref}`developer guide ` for details. + +

Scientific Use

+ +_tobac_ has been used in over 30 peer-reviewed publications, a subset of which are listed on our {ref}`publications page `. + +::: +:::{grid-item} + +

Citation

+ +If you use *tobac* for scholarly work, please cite it using the software citation: [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.2577046.svg)](https://doi.org/10.5281/zenodo.2577046), the original paper: + +> Heikenfeld, M., Marinescu, P. J., Christensen, M., Watson-Parris, D., Senf, F., van den Heever, S. C., and Stier, P.: tobac 1.2: towards a flexible framework for tracking and analysis of clouds in diverse datasets, Geosci. Model Dev., 12, 4551–4570, https://doi.org/10.5194/gmd-12-4551-2019, 2019 + +or, if you are using features introduced from v1.5.0 or above, please also cite the v1.5.0 paper: +> Sokolowsky, G. A., Freeman, S. W., Jones, W. K., Kukulies, J., Senf, F., Marinescu, P. J., Heikenfeld, M., Brunner, K. N., Bruning, E. C., Collis, S. M., Jackson, R. C., Leung, G. R., Pfeifer, N., Raut, B. A., Saleeby, S. M., Stier, P., and van den Heever, S. C.: tobac v1.5: introducing fast 3D tracking, splits and mergers, and other enhancements for identifying and analysing meteorological phenomena, Geosci. Model Dev., 17, 5309–5330, https://doi.org/10.5194/gmd-17-5309-2024, 2024. + +::: + + +:::: + + + + +:::{toctree} +:maxdepth: 1 +:hidden: + +Getting Started +Example Gallery +User Guide +Developer Guide +API +::: \ No newline at end of file diff --git a/doc/index.rst b/doc/index_old.rst similarity index 100% rename from doc/index.rst rename to doc/index_old.rst diff --git a/doc/requirements.txt b/doc/requirements.txt index 443a0ccd..aa1a7bf6 100644 --- a/doc/requirements.txt +++ b/doc/requirements.txt @@ -3,4 +3,6 @@ nbsphinx numpy sphinx_rtd_theme sphinx-gallery -pydata_sphinx_theme \ No newline at end of file +pydata_sphinx_theme +myst-parser +sphinx-design \ No newline at end of file