📝 Update Documentation Structure (#909)

- Use `Python 3.12` for docs build
- Update `copyright` year to `2025`
- Landing page now shows text from README 
- Update documentation structure
- Update `readthedocs` Build
- Remove `usage.rst`
- Rename Jupyter Notebooks to Usage Examples
- Show README for Usage Examples instead of TOC
- Reduce TOC depth for basic functionalities and pipelines
- Improve `README` quality.

.readthedocs.yml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-24.04
   tools:
-    python: "3.10"
+    python: "3.12"
   apt_packages:
     - openslide-tools
     - libopenjp2-7-dev

README.md

@@ -45,25 +45,21 @@
 
 ## Getting Started
 
-TIAToolbox is a computational pathology toolbox developed by TIA Centre that provides an end-to-end API for pathology image analysis using best practices. It is based on **[PyTorch](https://pytorch.org/)**, a popular deep learning framework that enables efficient and flexible implementation of state-of-the-art algorithms. TIAToolbox supports many features through a command-line interface and can integrate with standard PyTorch modules. It also offers tools for data loading, pre-processing, model inference, post-processing, and visualization. Whether you are a computational, biomedical, or clinical researcher, TIAToolbox can help you get started in digital pathology with minimal effort.
+TIAToolbox is a computational pathology toolbox developed by the TIA Centre. It provides an end-to-end API for pathology image analysis using best practices. Based on **[PyTorch](https://pytorch.org/)**, a popular deep learning framework, TIAToolbox enables efficient and flexible implementation of state-of-the-art algorithms. It supports many features through a command-line interface and can integrate with standard PyTorch modules. The toolbox offers tools for data loading, pre-processing, model inference, post-processing, and visualization. Whether you are a computational, biomedical, or clinical researcher, TIAToolbox can help you get started in digital pathology with minimal effort.
 
 ### All Users
 
-This package is for those interested in digital pathology: including graduate students, medical staff, members of the TIA Centre and of PathLAKE, and anyone, anywhere, who may find it useful. We will continue to improve this package, taking account of developments in pathology, microscopy, computing and related disciplines. Please send comments and criticisms to **[tia@dcs.warwick.ac.uk](mailto:tialab@dcs.warwick.ac.uk)**.
-
-**`tiatoolbox`** is a multipurpose name that we use for 1) a certain computer program, 2) a Python package of related programs, created by us at the TIA Centre to help people get started in Digital Pathology, 3) this repository, 4) a certain virtual environment.
+This package is designed for those interested in digital pathology, including graduate students, medical staff, members of the TIA Centre and PathLAKE, and anyone who may find it useful. We will continue to improve this package, taking into account developments in pathology, microscopy, computing, and related disciplines. Please send comments and feedback to **[tia@dcs.warwick.ac.uk](mailto:tialab@dcs.warwick.ac.uk)**.
 
 ### Developers
 
-Anyone wanting to contribute to this repository, please first look at our [Wiki](https://github.com/TissueImageAnalytics/tiatoolbox/wiki) and at our web page for [contributors](https://github.com/TissueImageAnalytics/tiatoolbox/blob/master/CONTRIBUTING.rst). See also the *Prepare for development* section of this document.
-
-### Links, if needed
+If you want to contribute to this repository, please first look at our [Wiki](https://github.com/TissueImageAnalytics/tiatoolbox/wiki) and our [contributor guidelines](https://github.com/TissueImageAnalytics/tiatoolbox/blob/master/CONTRIBUTING.rst). Also, see the *Prepare for development* section of this document.
 
-The [bash](https://www.gnu.org/software/bash) shell is available on all commonly encountered platforms. Commands in this README are in bash. Windows users can use the command prompt to install conda and python packages.
+### Useful Links
 
-[conda](https://github.com/conda/conda) is a management system for software packages and [virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html). To get `conda`, download [Anaconda](https://www.anaconda.com/), which includes hundreds of the most useful Python packages, using 2GB disk space. Alternatively, [miniconda](https://docs.conda.io/en/latest/miniconda.html) uses 400MB, and packages can be added as needed.
+The [bash](https://www.gnu.org/software/bash) shell is available on all commonly encountered platforms. Commands in this README are in bash. Windows users can use the command prompt to install conda and Python packages.
 
-[GitHub](https://github.com/about) is powered by the version control system [git](https://git-scm.com/), which has many users and uses. In GitHub, it is used to track versions of code and other documents.
+[conda](https://github.com/conda/conda) is a management system for software packages and [virtual environments](https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/environments.html). To get `conda`, download [Anaconda](https://www.anaconda.com/), which includes hundreds of the most useful Python packages, using 2GB of disk space. Alternatively, [miniconda](https://docs.conda.io/en/latest/miniconda.html) uses 400MB, and packages can be added as needed.
 
 ### Examples Taster
 

docs/basic_functionalities.rst

@@ -2,7 +2,7 @@ Basic Functionalities
 *********************
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :glob:
 
     _notebooks/jnb/*

docs/conf.py

@@ -84,7 +84,7 @@
 
 # General information about the project.
 project = "TIA Toolbox"
-copyright = "2023, TIA Lab"
+copyright = "2025, TIA Lab"
 author = "TIA Lab"
 
 # The version info for the project you're documenting, acts as replacement
@@ -2005,8 +2005,8 @@ def all_but_ipynb(dir_path, contents):
 )
 
 # shutil.copy(
-#     os.path.join(PROJ_ROOT, "docs/notebooks.rst"),
-#     os.path.join(PROJ_ROOT, "docs/_notebooks/notebooks.rst"),
+#     os.path.join(PROJ_ROOT, "docs/usage_examples.rst"),
+#     os.path.join(PROJ_ROOT, "docs/_notebooks/usage_examples.rst"),
 # )
 
 # Read in the file
@@ -2016,8 +2016,8 @@ def all_but_ipynb(dir_path, contents):
 # Replace the target string
 file_data = file_data.replace(".rst", ".html")
 file_data = file_data.replace(".ipynb", ".html")
-file_data = file_data.replace("../docs/", "../")
 file_data = file_data.replace("](./", "](./jnb/")
+file_data = file_data.replace("../docs/", "./")
 
 # Write the file out again
 with open("_notebooks/README.md", "w") as file:

docs/index.rst

@@ -1,18 +1,19 @@
 Welcome to TIA Toolbox's documentation!
 =======================================
 
-.. image:: tia_logo.png
-    :alt: alternate text
-    :align: center
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
+
+Index
+-----
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
 
     Readme <readme.rst>
     Installation <installation.rst>
-    Usage <usage.rst>
     Pre-trained Models <pretrained.rst>
-    Jupyter Notebooks <notebooks.rst>
+    Usage Examples <usage_examples.rst>
     Algorithms <algorithms.rst>
     Visualization <visualization.rst>
     API Reference <_autosummary/tiatoolbox>

docs/jnb_pipelines.rst

@@ -2,7 +2,7 @@ Pipelines
 *********
 
 .. toctree::
-    :maxdepth: 2
+    :maxdepth: 1
     :glob:
 
     _notebooks/jnb/inference-pipelines/*

docs/notebooks.rst → docs/usage_examples.rst

@@ -1,23 +1,20 @@
 Jupyter Notebooks
 #################
 
-.. toctree::
-    :maxdepth: 2
-
-    _notebooks/README.md
+.. include:: _notebooks/README.md
+   :parser: myst_parser.sphinx_
 
-|
+Index
+-----
 
 .. toctree::
-    :maxdepth: 3
-    :glob:
+    :maxdepth: 2
 
     Basic Functionalities <basic_functionalities.rst>
 
 |
 
 .. toctree::
-    :maxdepth: 3
-    :glob:
+    :maxdepth: 2
 
     Pipelines <jnb_pipelines.rst>