Documentation

.gitignore

@@ -8,3 +8,5 @@ dist/
 **/build
 *.grib
 !data/*.grib
+venv
+**/_build

VERSION

@@ -0,0 +1 @@
+0.0.3

docs/Makefile

@@ -6,7 +6,7 @@
 SPHINXOPTS    ?=
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = source
-BUILDDIR      = build
+BUILDDIR      = _build
 
 # Put it first so that "make" without argument is like "make help".
 help:

docs/conf.py

@@ -0,0 +1,114 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Imports -----------------------------------------------------------------
+
+import datetime
+import os
+import re
+import sys
+
+# -- Path manipulation--------------------------------------------------------
+
+sys.path.append(os.path.abspath("../tests"))
+
+
+# -- Run Doxygen -------------------------------------------------------------
+
+# Generate Doxygen documentation in the XML format.
+# assert subprocess.check_call("doxygen Doxyfile.in", stdout=subprocess.DEVNULL, shell=True) == 0
+
+
+# -- Project information -----------------------------------------------------
+
+project = "pyfdb"
+author = "ECMWF"
+
+year = datetime.datetime.now().year
+if year == 2021:
+    years = "2021"
+else:
+    years = "2021-%s" % (year,)
+
+copyright = "%s, %s" % (years, author)
+
+
+def parse_version(ver_str):
+    return re.sub("^((([0-9]+)\\.)+([0-9]+)).*", "\\1", ver_str)
+
+
+here = os.path.abspath(os.path.dirname(__file__))
+
+# Get the current version directly from the source.
+with open(os.path.join(here, "..", "VERSION"), "r") as f:
+    release = f.readline().strip()  # full version string
+
+version = parse_version(release)  # feature version
+
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = ["sphinx_rtd_theme", "sphinx_copybutton", "sphinx_tabs.tabs", "sphinxfortran.fortran_domain", "breathe"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# 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", "venv", "README.rst"]
+
+source_suffix = ".rst"
+master_doc = "index"
+pygments_style = "sphinx"
+
+highlight_language = "python"
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]
+
+html_context = {"css_files": ["_static/style.css"]}
+
+# Remove links to the reST sources from the page headers.
+html_show_sourcelink = False
+
+# Remove "Created using Sphinx" from the HTML footer.
+html_show_sphinx = False
+
+
+# -- Breathe configuration ---------------------------------------------------
+
+breathe_projects = {"pyfdb": "_build/xml/"}
+breathe_default_project = "pyfdb"
+breathe_domain_by_file_pattern = {
+    "*/pyfdb.py": "python",
+}
+
+
+# -- Sphinx copy button configuration -----------------------------------------------
+
+copybutton_selector = ".copybutton div.highlight pre"
+
+
+# -- Sphinx Tabs configuration -----------------------------------------------
+
+sphinx_tabs_disable_tab_closing = True
+
+# --- Enable figure numbering
+numfig = True

docs/content/license.rst

@@ -0,0 +1,10 @@
+License
+=======
+
+The license is as follows:
+
+|Licence|
+
+.. |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

docs/content/reference.rst

@@ -0,0 +1,47 @@
+How to reference FDB5
+---------------------
+
+Two publications, co-authored by Simon D. Smart, Tiago Quintino, Baudouin Raoult
+describe the FDB architecture and have been presented at PASC'17 
+`A Scalable Object Store for Meteorological and Climate Data`_ and 
+PASC'19 `A High-Performance Distributed Object-Store for Exascale Numerical Weather Prediction and Climate`_
+
+In the following the two BibTeX snippets:
+
+.. code-block:: latex
+
+   @inproceedings{10.1145/3093172.3093238,
+      author    = {Smart, Simon D. and Quintino, Tiago and Raoult, Baudouin},
+      title     = {A Scalable Object Store for Meteorological and Climate Data},
+      year      = {2017},
+      isbn      = {9781450350624},
+      publisher = {Association for Computing Machinery},
+      address   = {New York, NY, USA},
+      url       = {https://doi.org/10.1145/3093172.3093238},
+      doi       = {10.1145/3093172.3093238},
+      booktitle = {Proceedings of the Platform for Advanced Scientific Computing Conference},
+      articleno = {13},
+      numpages  = {8},
+      location  = {Lugano, Switzerland},
+      series    = {PASC ’17}
+   }
+
+   @inproceedings{10.1145/3324989.3325726,
+      author    = {Smart, Simon D. and Quintino, Tiago and Raoult, Baudouin},
+      title     = {A High-Performance Distributed Object-Store for Exascale Numerical Weather Prediction and Climate},
+      year      = {2019},
+      isbn      = {9781450367707},
+      publisher = {Association for Computing Machinery},
+      address   = {New York, NY, USA},
+      url       = {https://doi.org/10.1145/3324989.3325726},
+      doi       = {10.1145/3324989.3325726},
+      booktitle = {Proceedings of the Platform for Advanced Scientific Computing Conference},
+      articleno = {16},
+      numpages  = {11},
+      location  = {Zurich, Switzerland},
+      series    = {PASC ’19}
+   }
+
+
+.. _A Scalable Object Store for Meteorological and Climate Data: https://dl.acm.org/doi/pdf/10.1145/3093172.3093238
+.. _A High-Performance Distributed Object-Store for Exascale Numerical Weather Prediction and Climate: https://dl.acm.org/doi/pdf/10.1145/3324989.3325726

docs/content/technical-introduction.rst

@@ -0,0 +1,19 @@
+.. _technical-introduction-label:
+
+Technical 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 :doc:`mars` Archive
+
+.. toctree::
+   :maxdepth: 1
+
+   technical-introduction/api
+
+.. |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
+

docs/content/technical-introduction/api.rst

@@ -0,0 +1,42 @@
+.. index:: Reference; Python API
+   :name: python-reference
+
+Python API
+=======
+Work on adding documentation for the FDB API is in progress here.
+The corresponding C++ API can be found `here <https://fields-database.readthedocs.io/en/latest/>`_.
+
+.. doxygenclass:: pyfdb::pyfdb::FDB
+   :project: pyfdb
+   :members:
+   :protected-members:
+
+.. doxygenclass:: pyfdb::pyfdb::DataRetriever
+   :project: pyfdb
+   :members:
+   :protected-members:
+
+.. doxygenclass:: pyfdb::pyfdb::FDBException
+   :project: pyfdb
+   :members:
+   :protected-members:
+
+.. doxygenclass:: pyfdb::pyfdb::Key
+   :project: pyfdb
+   :members:
+   :protected-members:
+
+.. doxygenclass:: pyfdb::pyfdb::ListIterator
+   :project: pyfdb
+   :members:
+   :protected-members:
+
+.. doxygenclass:: pyfdb::pyfdb::PatchedLib
+   :project: pyfdb
+   :members:
+   :protected-members:
+
+.. doxygenclass:: pyfdb::pyfdb::Request
+   :project: pyfdb
+   :members:
+   :protected-members:

docs/index.rst

@@ -0,0 +1,30 @@
+Welcome to pyfdb's documentation!
+=================================
+
+The 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 MARS Archive.
+
+:ref:`technical-introduction-label`
+***************************************
+
+.. index:: Structure
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Structure
+
+   content/technical-introduction
+
+.. raw:: html
+
+   <hr>
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Misc
+
+   content/reference
+   content/license

docs/requirements.in

@@ -0,0 +1,8 @@
+sphinx
+sphinx-rtd-theme==0.5.2
+sphinx-copybutton==0.3.1
+sphinx-tabs
+breathe
+six
+sphinx-fortran
+sphinx-autobuild

docs/requirements.txt

@@ -0,0 +1,82 @@
+#
+# This file is autogenerated by pip-compile with Python 3.11
+# by the following command:
+#
+#    pip-compile --output-file=requirements.txt requirements.in
+#
+alabaster==0.7.16
+    # via sphinx
+babel==2.14.0
+    # via sphinx
+breathe==4.35.0
+    # via -r requirements.in
+certifi==2024.2.2
+    # via requests
+charset-normalizer==3.3.2
+    # via requests
+colorama==0.4.6
+    # via sphinx-autobuild
+docutils==0.16
+    # via
+    #   breathe
+    #   sphinx
+    #   sphinx-rtd-theme
+    #   sphinx-tabs
+idna==3.6
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.3
+    # via sphinx
+livereload==2.6.3
+    # via sphinx-autobuild
+markupsafe==2.1.5
+    # via jinja2
+packaging==23.2
+    # via sphinx
+pygments==2.17.2
+    # via
+    #   sphinx
+    #   sphinx-tabs
+requests==2.31.0
+    # via sphinx
+six==1.16.0
+    # via
+    #   -r requirements.in
+    #   livereload
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==5.3.0
+    # via
+    #   -r requirements.in
+    #   breathe
+    #   sphinx-autobuild
+    #   sphinx-copybutton
+    #   sphinx-rtd-theme
+    #   sphinx-tabs
+sphinx-autobuild==2024.2.4
+    # via -r requirements.in
+sphinx-copybutton==0.3.1
+    # via -r requirements.in
+sphinx-fortran==1.1.1
+    # via -r requirements.in
+sphinx-rtd-theme==0.5.2
+    # via -r requirements.in
+sphinx-tabs==3.4.5
+    # via -r requirements.in
+sphinxcontrib-applehelp==1.0.8
+    # via sphinx
+sphinxcontrib-devhelp==1.0.6
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.5
+    # via sphinx
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.7
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.10
+    # via sphinx
+tornado==6.4
+    # via livereload
+urllib3==2.2.1
+    # via requests