diff --git a/.gitignore b/.gitignore
index 66f6e40..cb5fa74 100644
--- a/.gitignore
+++ b/.gitignore
@@ -76,6 +76,7 @@ instance/
# Sphinx documentation
docs/_build/
+docs/source/auto_examples
# PyBuilder
.pybuilder/
diff --git a/docs/Makefile b/docs/Makefile
index 9c637f1..9af6711 100644
--- a/docs/Makefile
+++ b/docs/Makefile
@@ -14,6 +14,7 @@ help:
clean:
rm -rf $(BUILDDIR)/*
+ rm -rf $(SOURCEDIR)/auto_examples*
.PHONY: help Makefile
diff --git a/docs/requirements.txt b/docs/requirements.txt
index 4d27ad4..3ceff31 100644
--- a/docs/requirements.txt
+++ b/docs/requirements.txt
@@ -6,4 +6,5 @@ sphinx-design
pydata_sphinx_theme
sphinx-togglebutton
Jinja2
+myst-sphinx-gallery
git+https://github.com/Fanchengyan/FanInSAR.git@main
diff --git a/docs/source/_static/.$class_Structure.drawio.bkp b/docs/source/_static/.$class_Structure.drawio.bkp
deleted file mode 100644
index cb6c441..0000000
--- a/docs/source/_static/.$class_Structure.drawio.bkp
+++ /dev/null
@@ -1,10 +0,0 @@
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/source/_static/class_Structure.drawio b/docs/source/_static/class_Structure.drawio
deleted file mode 100644
index fe457a4..0000000
--- a/docs/source/_static/class_Structure.drawio
+++ /dev/null
@@ -1,51 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/source/_static/custom.css b/docs/source/_static/custom.css
index 60313cd..bf01200 100644
--- a/docs/source/_static/custom.css
+++ b/docs/source/_static/custom.css
@@ -1,10 +1,51 @@
-.bd-content {
- flex-grow: 1;
- max-width: 100%;
-}
+
.bd-page-width {
max-width: 100rem;
}
-.bd-main .bd-article-container {
- max-width: 100%;
+
+
+table {
+ width: auto; /* Override fit-content which breaks Styler user guide ipynb */
+}
+
+/* Main index page overview cards */
+
+.intro-card {
+ padding: 30px 10px 20px 10px;
+}
+
+.intro-card .sd-card-img-top {
+ margin: 10px;
+ height: 52px;
+ background: none !important;
+}
+
+.intro-card .sd-card-title {
+ color: var(--pst-color-secondary);
+ font-size: var(--pst-font-size-h5);
+ padding: 1rem 0rem 0.5rem 0rem;
+}
+
+.intro-card .sd-card-footer {
+ border: none !important;
+}
+
+.intro-card .sd-card-footer p.sd-card-text {
+ max-width: 220px;
+ margin-left: auto;
+ margin-right: auto;
+}
+
+/* .intro-card .sd-btn-secondary {
+ background-color: #6c757d !important;
+ border-color: #6c757d !important;
+}
+
+.intro-card .sd-btn-secondary:hover {
+ background-color: #5a6268 !important;
+ border-color: #545b62 !important;
+} */
+
+.card, .card img {
+ background-color: var(--pst-color-background);
}
diff --git a/docs/source/_static/datsets.drawio b/docs/source/_static/datsets.drawio
deleted file mode 100644
index 4898380..0000000
--- a/docs/source/_static/datsets.drawio
+++ /dev/null
@@ -1,51 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/docs/source/_static/doc_index/index_api.svg b/docs/source/_static/doc_index/index_api.svg
new file mode 100644
index 0000000..9cc960b
--- /dev/null
+++ b/docs/source/_static/doc_index/index_api.svg
@@ -0,0 +1,92 @@
+
+
+
+
diff --git a/docs/source/_static/doc_index/index_contribute.svg b/docs/source/_static/doc_index/index_contribute.svg
new file mode 100644
index 0000000..97fd155
--- /dev/null
+++ b/docs/source/_static/doc_index/index_contribute.svg
@@ -0,0 +1,75 @@
+
+
+
+
diff --git a/docs/source/_static/doc_index/index_example.svg b/docs/source/_static/doc_index/index_example.svg
new file mode 100644
index 0000000..3de22d4
--- /dev/null
+++ b/docs/source/_static/doc_index/index_example.svg
@@ -0,0 +1,70 @@
+
+
+
+
diff --git a/docs/source/_static/doc_index/index_get_start.svg b/docs/source/_static/doc_index/index_get_start.svg
new file mode 100644
index 0000000..ea4726c
--- /dev/null
+++ b/docs/source/_static/doc_index/index_get_start.svg
@@ -0,0 +1,69 @@
+
+
+
+
diff --git a/docs/source/_static/logo/icon.png b/docs/source/_static/logo/icon.png
index 04fa634..15737c4 100644
Binary files a/docs/source/_static/logo/icon.png and b/docs/source/_static/logo/icon.png differ
diff --git a/docs/source/_static/logo/icon.svg b/docs/source/_static/logo/icon.svg
index 9f9e98d..0c220bd 100644
--- a/docs/source/_static/logo/icon.svg
+++ b/docs/source/_static/logo/icon.svg
@@ -5,7 +5,7 @@
viewBox="0 0 500 500"
version="1.1"
id="svg11"
- sodipodi:docname="icon_v1.svg"
+ sodipodi:docname="icon.svg"
inkscape:version="1.3 (0e150ed, 2023-07-21)"
inkscape:export-filename="icon.png"
inkscape:export-xdpi="96"
@@ -29,7 +29,7 @@
inkscape:deskcolor="#d1d1d1"
inkscape:document-units="pt"
inkscape:zoom="0.66474411"
- inkscape:cx="553.59648"
+ inkscape:cx="552.09214"
inkscape:cy="534.79225"
inkscape:window-width="2560"
inkscape:window-height="1332"
@@ -1044,147 +1044,10 @@
sodipodi:start="2.4399127"
sodipodi:end="2.4198519"
sodipodi:arc-type="slice"
- d="M 185.99878,192.74902 A 140.49036,140.94046 0 0 1 202.07578,-5.4151897 140.49036,140.94046 0 0 1 399.68528,9.7192868 140.49036,140.94046 0 0 1 385.59037,208.0353 140.49036,140.94046 0 0 1 187.83949,194.89 l 105.46004,-93.11829 z" />`_ for each release. Below is the example of resulting ``BiBTeX`` record for FanInSAR 0.0.1 and a reference using ``APA`` 6th ed.
+
+
+
+.. code-block::
+ :caption: APA 6th ed reference
+
+ Fan, C., & Liu, L. (2024). FanInSAR: A Fancy InSAR time series library, in a Pythonic, fast, and flexible way (0.0.1). Zenodo. https://doi.org/10.5281/zenodo.11398347
+
+.. code-block:: bibtex
+ :caption: BiBTeX record
+
+ @software{fan2024FanInSAR,
+ author = {Fan, Chengyan and
+ Liu, Lin},
+ title = {{FanInSAR: A Fancy InSAR time series library, in a Pythonic, fast, and flexible way}},
+ month = may,
+ year = 2024,
+ publisher = {Zenodo},
+ version = {0.0.1},
+ doi = {10.5281/zenodo.11398347},
+ url = {https://doi.org/10.5281/zenodo.11398347}
+ }
diff --git a/docs/source/about/index.rst b/docs/source/about/index.rst
new file mode 100644
index 0000000..c12b330
--- /dev/null
+++ b/docs/source/about/index.rst
@@ -0,0 +1,12 @@
+.. _about:
+
+==============
+About FanInSAR
+==============
+
+.. toctree::
+ :maxdepth: 2
+ :caption: Contents:
+
+ terminology
+ citation
diff --git a/docs/source/terminology.rst b/docs/source/about/terminology.rst
similarity index 100%
rename from docs/source/terminology.rst
rename to docs/source/about/terminology.rst
diff --git a/docs/source/api/index.rst b/docs/source/api/index.rst
index 72252f9..6d7a98b 100644
--- a/docs/source/api/index.rst
+++ b/docs/source/api/index.rst
@@ -1,3 +1,5 @@
+.. _api:
+
=============
API Reference
=============
diff --git a/docs/source/conf.py b/docs/source/conf.py
index a952fba..50b0b12 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -11,6 +11,19 @@
author = "Fan Chengyan (Fancy)"
release = "v0.1"
+from pathlib import Path
+
+from myst_sphinx_gallery import GalleryConfig, __version__, generate_gallery
+
+myst_sphinx_gallery_config = GalleryConfig(
+ examples_dirs="../../examples",
+ gallery_dirs="auto_examples",
+ root_dir=Path(__file__).parent,
+ notebook_thumbnail_strategy="code",
+ thumbnail_strategy="last",
+)
+generate_gallery(myst_sphinx_gallery_config)
+
# -- General configuration ---------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -27,7 +40,8 @@
]
source_suffix = {
".rst": "restructuredtext",
- ".md": "markdown",
+ ".md": "myst-nb",
+ ".myst": "myst-nb",
}
myst_enable_extensions = ["colon_fence"]
myst_url_schemes = ["http", "https", "mailto"]
@@ -45,6 +59,7 @@
html_static_path = ["_static"]
html_css_files = ["custom.css"]
html_logo = "_static/logo/logo.png"
+html_favicon = "_static/logo/icon.svg"
html_theme_options = {
"show_toc_level": 2,
diff --git a/docs/source/contributing/index.rst b/docs/source/contributing/index.rst
new file mode 100644
index 0000000..c55bd49
--- /dev/null
+++ b/docs/source/contributing/index.rst
@@ -0,0 +1,153 @@
+.. _contributing:
+
+==================
+Contributing Guide
+==================
+
+
+We appreciate your help in improving this document and our library!
+
+Please `open an issue `_
+if you face any problems or have suggestions for improvements. We are always happy to help.
+
+
+If you are interested in contributing code or documentation, we strongly
+recommend that you install a development version of FanInSAR in a
+development environment. If you are unfamiliar with the git/github workflow,
+please see Github's guide to `contributing to projects
+`_.
+
+This guide assumes familiarity with the Github workflow and focuses on aspects
+specific to contributing to FanInSAR.
+
+
+Get Latest Source Code
+----------------------
+
+You can get the latest development source code from our `Github repository
+`_. Fork the repository and clone the forked repository to your local machine:
+
+.. code-block:: bash
+
+ git clone https://github.com//FanInSAR
+
+
+Create a Dedicated Environment
+------------------------------
+
+We strongly recommend that you create a virtual environment for developing FanInSAR to isolate it from other Python installations on your system.
+
+Create a new virtual environment using `conda `_:
+
+.. code-block:: bash
+
+ conda create -n faninsar python=3.10
+
+
+Activate the environment:
+
+.. code-block:: bash
+
+ conda activate faninsar
+
+
+Install Dependencies
+--------------------
+
+Most of the FanInSAR dependencies are listed in :file:`pyproject.toml` and can be
+installed from those files:
+
+.. code-block:: bash
+
+ python -m pip install ".[dev]"
+
+FanInSAR requires that `setuptools
+`_ is installed. It is
+usually packaged with python, but if necessary can be installed using ``pip``:
+
+.. code-block:: bash
+
+ python -m pip install setuptools
+
+
+
+Install for Development
+-----------------------
+
+Editable installs means that the environment Python will always use the most
+recently changed version of your code. To install Sphinx Gallery in editable
+mode, ensure you are in the sphinx-gallery directory
+
+.. code-block:: bash
+
+ cd FanInSAR
+
+Then install using the editable flag:
+
+.. code-block:: bash
+
+ python -m pip install -e .
+
+
+Run Tests
+---------
+
+Check that you are all set by running the tests:
+
+.. code-block:: bash
+
+ python -m pytest
+
+Install pre-commit hooks
+------------------------
+
+pre-commit hooks check for things like spelling and formatting in contributed
+code and documentation. To set up pre-commit hooks:
+
+.. code-block:: bash
+
+ pre-commit install
+
+This will install the pre-commit hooks in your local repository. You can run the hooks manually with:
+
+.. code-block:: bash
+
+ pre-commit run --all-files
+
+Testing
+-------
+
+All code contributions should be tested. We use the `pytest
+`_ testing framework to build test
+pages. Tests can be found in :file:`faninsar/tests`.
+
+
+
+Build the documentation
+-----------------------
+
+If you are contributing to the documentation, you can build the docs locally to see how your changes will look.
+
+To build the docs, run:
+
+
+.. code-block:: bash
+
+ cd docs
+ make html
+
+After building the docs, you can view them by opening :file:`_build/html/index.html` in your browser.
+
+To clean up the build files and generated galleries, run:
+
+.. code-block:: bash
+
+ make clean
+
+
+Contributing
+------------
+
+When contributing to FanInSAR, please follow the `Contributor Covenant
+`_ in all
+your interactions with the project.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index f4fecbc..ab10502 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -26,39 +26,97 @@ Highlight Features
- **Fast**: The core computation in FanInSAR is implemented using ``PyTorch``, a high-performance deep learning library. This allows for efficient processing on both CPU and GPU, enabling faster execution.
- **Flexible**: FanInSAR is designed to be flexible, allowing for customization and extension. Users can easily inherit classes or customize the processing pipeline for their specific needs.
-.. note::
- 1. FanInSAR is under active development and is currently in the alpha stage. Its API may change in the future until it reaches a stable version.
- 2. If you have any questions, suggestions, or issues, please feel free to open an issue or discussion on our GitHub repository at `GitHub Issues `_ or `GitHub Discussions `_.
+.. grid:: 1 2 2 2
+ :gutter: 5
+ :class-container: sd-text-center
+ :padding: 4
+
+
+ .. grid-item-card:: Quick Overview
+ :img-top: /_static/doc_index/index_get_start.svg
+ :class-card: intro-card
+ :shadow: md
+
+ Learn how to use **FanInSAR** and discover its capabilities with a quick overview.
+
+ +++
+
+ .. button-ref:: quick_overview
+ :ref-type: ref
+ :click-parent:
+ :color: secondary
+ :expand:
+
+ To the Quick Start
+
+ .. grid-item-card:: Examples Gallery
+ :img-top: /_static/doc_index/index_example.svg
+ :class-card: intro-card
+ :shadow: md
+
+ Explore the examples to see how **FanInSAR** can be used in practice.
+
+ +++
+
+ .. button-ref:: gallery_header
+ :ref-type: ref
+ :click-parent:
+ :color: secondary
+ :expand:
+
+ To the Examples Gallery
-Citation
---------
+ .. grid-item-card:: API Reference
+ :img-top: /_static/doc_index/index_api.svg
+ :class-card: intro-card
+ :shadow: md
-.. code-block::
+ Dive into the **FanInSAR** API Reference to learn more about the available classes and methods.
- Fan, C., & Liu, L. (2024). FanInSAR: A Fancy InSAR time series library, in a Pythonic, fast, and flexible way (0.0.1). Zenodo. https://doi.org/10.5281/zenodo.11398347
+ +++
+
+ .. button-ref:: api
+ :ref-type: ref
+ :click-parent:
+ :color: secondary
+ :expand:
+
+ To the API Reference
+
+ .. grid-item-card:: Contributing Guide
+ :img-top: /_static/doc_index/index_contribute.svg
+ :class-card: intro-card
+ :shadow: md
+
+ Do you want to contribute to **FanInSAR**? Check out the contributing guide.
+
+ +++
+
+ .. button-ref:: contributing
+ :ref-type: ref
+ :click-parent:
+ :color: secondary
+ :expand:
+
+ To the Contributing Guide
+
+
+.. note::
+
+ 1. FanInSAR is under active development and is currently in the alpha stage. Its API may change in the future until it reaches a stable version.
+ 2. If you have any questions, suggestions, or issues, please feel free to open an issue or discussion on our GitHub repository at `GitHub Issues `_ or `GitHub Discussions `_.
-.. code-block:: bibtex
- @software{fan2024FanInSAR,
- author = {Fan, Chengyan and
- Liu, Lin},
- title = {{FanInSAR: A Fancy InSAR time series library, in a Pythonic, fast, and flexible way}},
- month = may,
- year = 2024,
- publisher = {Zenodo},
- version = {0.0.1},
- doi = {10.5281/zenodo.11398347},
- url = {https://doi.org/10.5281/zenodo.11398347}
- }
.. toctree::
- :maxdepth: 2
- :caption: Contents:
-
- install
- user_guide/index
- examples/index
- api/index
- terminology
+ :maxdepth: 2
+ :hidden:
+
+ install
+ user_guide/index
+ auto_examples/index
+ api/index
+ Contributing
+ About
diff --git a/docs/source/user_guide/quick_start.ipynb b/docs/source/user_guide/quick_start.ipynb
index 72877fd..7d5d24f 100644
--- a/docs/source/user_guide/quick_start.ipynb
+++ b/docs/source/user_guide/quick_start.ipynb
@@ -4,6 +4,8 @@
"cell_type": "markdown",
"metadata": {},
"source": [
+ "(quick_overview)=\n",
+ "\n",
"# Quick Overview\n",
"\n",
"This tutorial will help you get started with basic usage of the FanInSAR library. We will cover the following topics:\n",
diff --git a/docs/source/examples/warp/index.rst b/examples/01-warp/GALLERY_HEADER.rst
similarity index 70%
rename from docs/source/examples/warp/index.rst
rename to examples/01-warp/GALLERY_HEADER.rst
index bd92b1f..b88e656 100644
--- a/docs/source/examples/warp/index.rst
+++ b/examples/01-warp/GALLERY_HEADER.rst
@@ -5,10 +5,3 @@ Warp Example
============
This section demonstrates how to warp the raster datasets, such as reprojecting and resampling the raster datasets.
-
-.. toctree::
- :maxdepth: 2
-
- reproject
- resample
- match_raster
diff --git a/docs/source/examples/warp/match_raster.ipynb b/examples/01-warp/match_raster.ipynb
similarity index 100%
rename from docs/source/examples/warp/match_raster.ipynb
rename to examples/01-warp/match_raster.ipynb
diff --git a/docs/source/examples/warp/reproject.ipynb b/examples/01-warp/reproject.ipynb
similarity index 100%
rename from docs/source/examples/warp/reproject.ipynb
rename to examples/01-warp/reproject.ipynb
diff --git a/docs/source/examples/warp/resample.ipynb b/examples/01-warp/resample.ipynb
similarity index 100%
rename from docs/source/examples/warp/resample.ipynb
rename to examples/01-warp/resample.ipynb
diff --git a/docs/source/examples/ARPs.ipynb b/examples/ARPs/ARPs.ipynb
similarity index 100%
rename from docs/source/examples/ARPs.ipynb
rename to examples/ARPs/ARPs.ipynb
diff --git a/examples/ARPs/GALLERY_HEADER.rst b/examples/ARPs/GALLERY_HEADER.rst
new file mode 100644
index 0000000..604b814
--- /dev/null
+++ b/examples/ARPs/GALLERY_HEADER.rst
@@ -0,0 +1,3 @@
+========================================
+Automatically Selecting Reference Points
+========================================
diff --git a/docs/source/examples/index.rst b/examples/GALLERY_HEADER.rst
similarity index 61%
rename from docs/source/examples/index.rst
rename to examples/GALLERY_HEADER.rst
index 2d57dcf..5eff416 100644
--- a/docs/source/examples/index.rst
+++ b/examples/GALLERY_HEADER.rst
@@ -1,13 +1,7 @@
+.. _gallery_header:
+
========
Examples
========
We provide a number of examples to help you get started with using the **FanInSAR** package.
-
-
-.. toctree::
- :maxdepth: 1
- :caption: Contents:
-
- warp/index
- ARPs