Documentation

.gitignore

@@ -1 +1,13 @@
+cmake
+.cache
 .vscode
+.clangd
+**/venv
+**/_build
+build
+install.sh
+**/.DS_Store
+**/Doxyfile.in.bak
+
+# LLVM debug
+launch.json

.readthedocs.yaml

@@ -0,0 +1,35 @@
+# Read the Docs configuration file for Sphinx projects
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+    # You can also specify other tool versions:
+    # nodejs: "20"
+    # rust: "1.70"
+    # golang: "1.20"
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py
+  # You can configure Sphinx to use a different builder, for instance use the dirhtml builder for simpler URLs
+  # builder: "dirhtml"
+  # Fail on all warnings to avoid broken references
+  # fail_on_warning: true
+
+# Optionally build your docs in additional formats such as PDF and ePub
+# formats:
+#   - pdf
+#   - epub
+
+# Optional but recommended, declare the Python requirements required
+# to build your documentation
+# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
+python:
+   install:
+     - requirements: docs/requirements.txt

docs/README.rst

@@ -27,10 +27,15 @@ Build dependencies:
 :CMake: For use and installation see http://www.cmake.org/
 :ecbuild: ECMWF library of CMake macros ()
 
+Optional dependencies for building documentation:
+
+:sphinx-build: Create documentation from reStructuredText, see https://www.sphinx-doc.org/en/master/man/sphinx-build.html
+:breathe: Bridge between Sphinx and Doxygen, see https://breathe.readthedocs.io/en/latest/
+
 Installation
 ============
 
-fdb employs an out-of-source build/install based on CMake.
+FDB employs an out-of-source build/install based on CMake.
 
 Make sure ecbuild is installed and the ecbuild executable script is found ( ``which ecbuild`` ).
 

docs/conf.py

@@ -61,7 +61,8 @@ def parse_version(ver_str):
     "sphinx_copybutton",
     "sphinx_tabs.tabs",
     "sphinxfortran.fortran_domain",
-    "breathe",
+    "sphinx_toolbox.collapse",
+    "breathe"
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -70,7 +71,7 @@ def parse_version(ver_str):
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store", "venv", "README.rst"]
 
 source_suffix = ".rst"
 master_doc = "index"
@@ -121,3 +122,6 @@ def parse_version(ver_str):
 # -- Sphinx Tabs configuration -----------------------------------------------
 
 sphinx_tabs_disable_tab_closing = True
+
+# --- Enable figure numbering
+numfig = True

docs/content/architectural-introduction.rst

@@ -0,0 +1,26 @@
+.. _architectural-introduction-label:
+
+Architectural Introduction
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+|Licence|
+
+FDB (Fields DataBase) is a domain-specific object store developed at ECMWF for storing, indexing and retrieving GRIB data. Each GRIB message is stored as a field and indexed trough semantic metadata (i.e. physical variables such as temperature, pressure, ...).
+A set of fields can be retrieved specifying a request using a specific language developed for accessing :ref:`mars-request-label` Archive
+
+FDB exposes a C++ API as well as CLI :ref:`tools-label`, for further information, see :ref:`technical-introduction-label`.
+
+The overall structure of the system the FDB is operating on can be seen in:
+
+
+.. toctree::
+   :maxdepth: 1
+
+   architecture/introduction
+   architecture/overview
+
+
+.. |Licence| image:: https://img.shields.io/badge/License-Apache%202.0-blue.svg
+   :target: https://github.com/ecmwf/fdb/blob/develop/LICENSE
+   :alt: Apache Licence
+