Merge branch 'docs_changelog' into 'main'

Docs: add changelog and discussions link and minor improvements

See merge request !150

CHANGELOG.md

-# Changelog
+# Release notes
 
 ## [unpublished]
 
@@ -28,9 +28,9 @@
   * `AComponent` is now `Component`
   * `ATimeComponent` is now `TimeComponent`
 * Changed arguments for `create_connector()`
-  * Removed `required_out_infos` 
+  * Removed `required_out_infos`
   * Renamed `required_in_data` to `pull_data`
-* All error types are in module `errors` now, and re-exported at top level 
+* All error types are in module `errors` now, and re-exported at top level
 
 ## [v0.4.0-rc.2]
 
@@ -47,7 +47,7 @@
 * Connect phase of scheduler can be called separately from run (!99)
 * No need to set component status in constructor anymore (!100)
 
-### Other  
+### Other
 
 * Components are allowed to be in state VALIDATED at the end of a run (i.e. not updated) (!97)
 * Component connector checks that inputs and outputs referenced in arguments actually exist (!101)
@@ -56,12 +56,12 @@
 
 ### Data and metadata rework
 
-* Grid specifications for structured and unstructured grids (!74):  
+* Grid specifications for structured and unstructured grids (!74):
   `RectilinearGrid`, `UniformGrid`, `EsriGrid`, `UnstructuredGrid` and `UnstructuredPoints`
 * Use of `xarray.DataArray` for all exchanged data (!74)
 * All exchanged data must have `pint` units (can be "dimensionless") (!74)
 * Metadata about grid specification, units and other metadata is exchanged before the first data exchange (!77)
-* Metadata exchange is iterative and bi-directional (!77)  
+* Metadata exchange is iterative and bi-directional (!77)
   Components can depend on metadata from source or target components
 * Inputs check compatibility of incoming metadata with own requirements (!77)
 * Inputs and outputs check compatibility of incoming data with metadata (!77)
@@ -120,3 +120,14 @@
 
 * Uses Python's `datetime` and `timedelta` for all time-related parameters
 * Removed temporal sum integration adapter
+
+## [v0.1.0]
+
+* initial release of FINAM
+
+[unpublished]: https://git.ufz.de/FINAM/finam/-/compare/v0.4.0-rc.2...main
+[v0.4.0-rc.2]: https://git.ufz.de/FINAM/finam/-/compare/v0.4.0-rc.1...v0.4.0-rc.2
+[v0.4.0-rc.1]: https://git.ufz.de/FINAM/finam/-/compare/v0.3.0...v0.4.0-rc.1
+[v0.3.0]: https://git.ufz.de/FINAM/finam/-/compare/v0.2.0...v0.3.0
+[v0.2.0]: https://git.ufz.de/FINAM/finam/-/compare/v0.1.0...v0.2.0
+[v0.1.0]: https://git.ufz.de/FINAM/finam/-/commits/v0.1.0

docs/source/changelog.rst

+.. include:: ../../CHANGELOG.md
+   :parser: myst_parser.sphinx_

docs/source/conf.py

 import datetime
 
+from finam import __version__ as finam_version
+
 # Configuration file for the Sphinx documentation builder.
 #
 # For the full list of built-in configuration values, see the documentation:
@@ -11,6 +13,8 @@ import datetime
 project = "finam"
 copyright = f"2021 - {datetime.datetime.now().year}, Team LandTECH"
 author = "FINAM Developers"
+version = finam_version
+release = finam_version
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
@@ -20,7 +24,6 @@ extensions = [
     "sphinx_design",
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
-    "sphinx.ext.autosectionlabel",
     "sphinx.ext.intersphinx",
     "sphinx.ext.doctest",
     "sphinx.ext.viewcode",
@@ -34,11 +37,8 @@ extensions = [
 autosummary_generate = True
 # dont show __init__ docstring
 autoclass_content = "class"
-# for uniqur labels/anchors
-autosectionlabel_prefix_document = True
 # sort class members
-autodoc_member_order = "groupwise"
-# autodoc_member_order = 'bysource'
+autodoc_member_order = "bysource"
 
 # Notes in boxes
 napoleon_use_admonition_for_notes = True
@@ -83,6 +83,7 @@ html_favicon = "_static/logo.svg"
 html_theme_options = {
     "page_sidebar_items": ["page-toc"],
     "footer_items": ["copyright"],
+    "header_links_before_dropdown": 6,
     "show_nav_level": 2,
     "show_toc_level": 2,
     "icon_links": [
@@ -103,6 +104,10 @@ html_theme_options = {
     ],
     "external_links": [
         {"name": "Examples", "url": "https://git.ufz.de/FINAM/finam-examples"},
+        {
+            "name": "Get Help",
+            "url": "https://github.com/finam-ufz/finam/discussions",
+        },
     ],
 }
 

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

@@ -13,7 +13,7 @@ without an explicit order. Even circular!
 
 For convenience, :class:`.Component` (and thus :class:`.TimeComponent`) provides the methods
 :meth:`.Component.create_connector` and :meth:`.Component.try_connect` for handling this phase.
-See section `Implementing The Connect Phase <implementing>`_.
+See section `Implementing The Connect Phase`_.
 
 Metadata
 --------
@@ -37,7 +37,7 @@ It can then generate data matching the expected metadata.
 Metadata must be provided for all inputs and all outputs.
 This can happen in :meth:`.Component._initialize` when constructing inputs and outputs.
 If the information is not available there yet (because it depends on linked components),
-it can happen in :meth:`.Component._connect` via :meth:`.Component.try_connect()` (see section `Implementing The Connect Phase <implementing>`_).
+it can happen in :meth:`.Component._connect` via :meth:`.Component.try_connect()` (see section `Implementing The Connect Phase`_).
 
 For details on the metadata itself, see chapter :doc:`./data_metadata`.
 
@@ -72,10 +72,8 @@ To avoid this, there are the two different states :attr:`.ComponentStatus.CONNEC
 If, during an iteration, no component signals any progress (:attr:`.ComponentStatus.CONNECTING`, or newly :attr:`.ComponentStatus.CONNECTED`), initialization has stalled.
 The scheduler raises an error and informs about components that could not complete the process.
 
-.. _implementing:
-
-Implementing The Connect Phase |trade|
---------------------------------------
+Implementing The Connect Phase
+------------------------------
 
 The iterative connection process is largely managed by two methods provided by :class:`.Component`:
 

docs/source/index.md

@@ -67,7 +67,7 @@ See our gallery of examples that use FINAM.
 
 ## News
 
-News from the [FINAM Blog](blog/index).
+News from the [FINAM Blog](blog/index). See also the [Changelog](changelog).
 
 ```{postlist} 3
 :format: "{title}"
@@ -79,6 +79,7 @@ News from the [FINAM Blog](blog/index).
 ## FINAM Book
 
 Information about using, configuring and exploring FINAM.
+If you still have questions, check our [Discussions page](https://github.com/finam-ufz/finam/discussions) to get help.
 
 ```{toctree}
 :includehidden:
@@ -103,3 +104,8 @@ Announcements, cookbook recipes and user experience with FINAM.
 :maxdepth: 2
 blog/index
 ```
+
+```{toctree}
+:hidden:
+changelog
+```