fix index pages and page titles

MANIFEST.in

@@ -2,5 +2,5 @@ prune *
 graft src
 graft tests
 
-include LICENSE README.md CHANGELOG.md pyproject.toml
+include LICENSE README.md pyproject.toml
 global-exclude __pycache__ *.py[cod] .*

docs/source/finam-book/about.rst

-# About this book
+===============
+About this book
+===============
 
 This book has multiple purposes:
 
-* [FINAM principles](./principles/index): Explain the basic principles of FINAM to the interested audience
-* [Using FINAM](./usage/index): Teach end users how to set up and run FINAM compositions
-* [Developing for FINAM](./development/index): Teach developers how to implement FINAM modules, and how to wrap existing models for coupling
+* :doc:`principles/index` -- Explain the basic principles of FINAM to the interested audience
+* :doc:`usage/index` -- Teach end users how to set up and run FINAM compositions
+* :doc:`development/index` -- Teach developers how to implement FINAM modules, and how to wrap existing models for coupling
 
 All except the chapters on principles require some Python programming skills.
 We do not teach Python in this book, so different levels of programming knowledge
 are assumed for certain chapters. Read on for details...
 
-## Requirements
+Requirements
+------------
 
-The first chapters under [FINAM principles](./principles/index) are crucial for understanding how FINAM works.
+The first chapters under :doc:`principles/index` are crucial for understanding how FINAM works.
 They contain only textual and visual descriptions. They contain no code and require no programming knowledge.
 Read this first!
 
-The chapters under [Using FINAM](./usage/index) are dedicated to users
+The chapters under :doc:`usage/index` are dedicated to users
 that want to set up FINAM compositions using existing modules.
 Compositions are created through Python scripts.
 These chapters require some basic Python knowledge for writing simple scripts.
 
-The chapters under [Developing for FINAM](./development/index) are dedicated to developers
+The chapters under :doc:`development/index` are dedicated to developers
 that want to build modules for FINAM, or wrap existing models or libraries for the use in FINAM compositions.
 To write modules following these chapters, intermediate knowledge of Python is required.
 Particularly, developers need some basic understanding of object-oriented programming in Python.

docs/source/finam-book/development/adapters.rst

-# Writing adapters
+================
+Writing adapters
+================
 
 This chapter provides a step-by-step guide to implement adapters in pure Python.
 For writing Python bindings for other languages, see [Python bindings](./py-bindings).

docs/source/finam-book/development/components.rst

-# Writing components
+==================
+Writing components
+==================
 
 This chapter provides a step-by-step guide to implement a component with time (e.g. a model) in pure Python.
 For writing Python bindings for other languages, see [Python bindings](./py-bindings).

docs/source/finam-book/development/connect_phase.rst

-# The Connect Phase ™
+=========================
+The Connect Phase ™
+=========================
 
 The "Connect Phase" between linking components and running the composition is a crucial foundation for the coupling principle of FINAM.
 

docs/source/finam-book/development/data_metadata.rst

-# Data and metadata
+=================
+Data and metadata
+=================
 
 This chapter explains data and metadata in FINAM.
 

docs/source/finam-book/development/index.rst

-# Developing for FINAM
+====================
+Developing for FINAM
+====================
 
 The following chapters target developers that want to prepare their existing models for use in FINAM, or that want to write FINAM-compatible models from scratch.
 
 Besides preparation of models, implementation of adapters that mediate data between models is also covered.
 
-```{toctree}
-:hidden:
-interfaces
-components
-adapters
-data_metadata
-connect_phase
-logging
-special_components
-py-bindings
-```
+.. toctree::
+    :hidden:
+
+    interfaces
+    components
+    adapters
+    data_metadata
+    connect_phase
+    logging
+    special_components
+    py-bindings

docs/source/finam-book/development/logging.rst

-# Logging for components
+======================
+Logging for components
+======================
 
 This chapter provides information on how to use logging in components.
 

docs/source/finam-book/development/py-bindings.rst

-# Python bindings
+===============
+Python bindings
+===============
 
 FINAM requires Python bindings for coupling components or models written in a language other than Python, like C++, Fortran or Rust.
 

docs/source/finam-book/development/special_components.rst

-# Components without time step
+============================
+Components without time step
+============================
 
 So far, we mainly dealt with components that have an internal time step.
 In some cases, however, components without an internal time step can be useful.

docs/source/finam-book/index.rst

-# FINAM Book
+==========
+FINAM Book
+==========
 
 FINAM is an open-source component-based model coupling framework for environmental models.
 It aims at enabling bi-directional online couplings of models for different compartments like geo-, hydro-, pedo- and biosphere.
 
-```{image} images/logo_large.svg
-:alt: FINAM Logo
-:class: dark-light p-2
-:width: 300px
-:target: https://finam.pages.ufz.de
-```
+.. image:: images/logo_large.svg
+    :alt: FINAM Logo
+    :class: dark-light p-2
+    :width: 300px
+    :target: https://finam.pages.ufz.de
 
 The framework is built in Python, with well-defined interfaces for data exchange.
 This approach allows for coupling of models irrespective of their internal structure, architecture or programming language.
 
 
-* [About this book](about) -- The purpose of this book, and how to read it.
-* [FINAM principles](principles/index) -- Explains basic principles of the FINAM framework that are of interest for users as well as developers.
-* [Using FINAM](usage/index) -- Guide for users that aim at coupling existing models.
-* [Developing for FINAM](development/index) -- Guide for developers on how to prepare models for FINAM, and how to implement adapters.
-
-```{toctree}
-:hidden:
-:maxdepth: 1
-self
-```
-
-```{toctree}
-:hidden:
-:maxdepth: 1
-:caption: Sections
-about
-principles/index
-usage/index
-development/index
-```
+* :doc:`about` -- The purpose of this book, and how to read it.
+* :doc:`principles/index` -- Explains basic principles of the FINAM framework that are of interest for users as well as developers.
+* :doc:`usage/index` -- Guide for users that aim at coupling existing models.
+* :doc:`development/index` -- Guide for developers on how to prepare models for FINAM, and how to implement adapters.
+
+.. toctree::
+    :hidden:
+    :maxdepth: 1
+
+    self
+
+.. toctree::
+    :hidden:
+    :maxdepth: 1
+    :caption: Sections
+
+    about
+    principles/index
+    usage/index
+    development/index

docs/source/finam-book/principles/components_adapters.rst

-# Components and Adapters
+=======================
+Components and Adapters
+=======================
 
-Models are wrapped according to the interfaces into independent *components*.
-Communication works over so-called *adapters* that are plugged between models or other components.
+Models are wrapped according to the interfaces into independent *Components*.
+Communication works over so-called *Adapters* that are plugged between models or other components.
 These adapters are responsible for transforming data between one model's output and the receiving model's expected input.
 Examples are spatio-temporal rescaling or coordinate transforms.
 
 FINAM enables setting up a consistent and flexible data stream workflow involving models and drivers, as well as data pre- and post-processing (e.g. visualization).
 
-## Components
+Components
+----------
 
 Components are the primary entities that are coupled in FINAM.
 
 A component can have multiple inputs and outputs to exchange data with other components.
 
-![Component](../images/component.svg)
-
-*Figure 1: A FINAM component*
+.. image:: ../images/component.svg
+    :alt: Component
+    :class: dark-light p-2
+    :caption: *Figure 1: A FINAM component*
 
 There are two principle types of components:
 

docs/source/finam-book/principles/coupling_scheduling.rst

-# Coupling and Scheduling
+=======================
+Coupling and Scheduling
+=======================
 
 ## Coupling
 

docs/source/finam-book/principles/data_flow.rst

-# Data flow
+=========
+Data flow
+=========
 
 FINAM is based on a **hybrid push-pull information flow**. Components and adapters "push" data updates to their outputs.
 These default outputs (`Output`) store the data,

docs/source/finam-book/principles/index.rst

-# FINAM principles
+================
+FINAM principles
+================
 
 This chapter describes:
 
-* What [Components and Adapters](components_adapters) are
-* How [Coupling and Scheduling](coupling_scheduling) works
-* How [Data flow](data_flow) is managed
-* How FINAM treats [Metadata and time](metadata.md)
+* What :doc:`components_adapters` are
+* How :doc:`coupling_scheduling` works
+* How :doc:`data_flow` is managed
+* How FINAM treats :doc:`metadata`
 
-```{toctree}
-:hidden:
-components_adapters
-coupling_scheduling
-data_flow
-metadata
-```
+.. toctree::
+    :hidden:
+
+    components_adapters
+    coupling_scheduling
+    data_flow
+    metadata

docs/source/finam-book/principles/metadata.rst

-# Metadata and time
+=================
+Metadata and time
+=================
 
 In FINAM, data has certain information associated.
 This is necessary to ensure valid coupling and is one of the foundations for the ease of use of FINAM.

docs/source/finam-book/usage/components_adapters.rst

-# Components and adapters
+=======================
+Components and adapters
+=======================
 
 This chapter lists known components and adapters for use in FINAM compositions.
 

docs/source/finam-book/usage/coupling_scripts.rst

-# Model coupling scripts
+======================
+Model coupling scripts
+======================
 
 Coupling setups are created and executed using Python scripts.
 

docs/source/finam-book/usage/index.rst

-# Using FINAM
+===========
+Using FINAM
+===========
 
 The following chapters target users that want to couple models that are already prepared for FINAM.
 
-Chapter [Installation](installation) covers how to install the FINAM Python package.
+Chapter :doc:`installation` covers how to install the FINAM Python package.
 
-Chapter [Model coupling scripts](coupling_scripts) covers how to write Python scripts that compose and run model coupling setups.
+Chapter :doc:`coupling_scripts` covers how to write Python scripts that compose and run model coupling setups.
 
-Chapter [Known components and adapters](components_adapters) provides a list of known FINAM components and adapters for the use in coupling scripts.
+Chapter :doc:`components_adapters` provides a list of known FINAM components and adapters for the use in coupling scripts.
 
-```{toctree}
-:hidden:
-installation
-coupling_scripts
-components_adapters
-```
+.. toctree::
+    :hidden:
+
+    installation
+    coupling_scripts
+    components_adapters

docs/source/finam-book/usage/installation.rst

-# Installation
+============
+Installation
+============
 
 FINAM can be installed using `pip`, from a local clone of the Git repository. See the [`pip` website](https://pypi.org/project/pip/) for how to get `pip`.