Initialize documentation

.gitignore

@@ -129,3 +129,6 @@ dmypy.json
 
 # Pyre type checker
 .pyre/
+
+# visual studio
+.vscode/

.readthedocs.yaml

@@ -0,0 +1,27 @@
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04  # is required: see https://github.com/readthedocs/readthedocs.org/issues/8912
+  tools:
+    python: "3.10"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+  configuration: docs/source/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+# formats:
+# - pdf
+
+# Optionally set requirements required to build your docs
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        - docs

docs/Makefile

@@ -0,0 +1,44 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+PINEKODIR = ../src/eko
+PINEKOOUT = $(SOURCEDIR)/modules/pineko
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+server:
+	python3 -m http.server 8000 --bind 127.0.0.1 --directory $(BUILDDIR)/html
+
+view: html
+	$(BROWSER) $(BUILDDIR)/html/index.html
+
+
+clean:
+	rm -rf build
+	rm -rf _build
+
+cleanall: clean clean-todos
+	rm -rf $(PINEKOOUT)
+
+# TODOs
+todos:
+	python generate_code_todos.py "$(PINEKODIR)" "$(TODOOUTFILE)"
+
+clean-todos:
+	rm "$(TODOOUTFILE)"

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,103 @@
+# -*- coding: utf-8 -*-
+# 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
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+# import os
+# import sys
+# sys.path.insert(0, os.path.abspath('.'))
+
+import inspect
+import pathlib
+
+import pineko
+
+here = pathlib.Path(__file__).absolute().parent
+
+# -- Project information -----------------------------------------------------
+
+project = "pineko"
+copyright = "2022, Andrea Barontini, Alessandro Candido, Felix Hekhorn"
+author = "Andrea Barontini, Alessandro Candido, Felix Hekhorn"
+
+
+# -- 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.ext.autodoc",
+    "sphinx.ext.doctest",
+    "sphinx.ext.intersphinx",
+    "sphinx.ext.todo",
+    "sphinx.ext.coverage",
+    "sphinx.ext.mathjax",
+    "sphinx.ext.ifconfig",
+    "sphinx.ext.viewcode",
+    "sphinx.ext.autosectionlabel",
+    "sphinxcontrib.bibtex",
+    "sphinx.ext.napoleon",
+    "sphinx.ext.graphviz",
+    "sphinx.ext.extlinks",
+]
+autosectionlabel_prefix_document = True
+# autosectionlabel_maxdepth = 10
+# Allow to embed rst syntax in  markdown files.
+enable_eval_rst = True
+# The master toctree document.
+master_doc = "index"
+bibtex_bibfiles = ["refs.bib"]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# The suffix(es) of source filenames.
+# You can specify multiple suffix as a list of string:
+#
+source_suffix = {
+    ".rst": "restructuredtext",
+    ".txt": "restructuredtext",
+}
+use_index=True
+# 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 = ["shared/*"]
+
+# A string to be included at the beginning of all files
+shared = here / "shared"
+rst_prolog = "\n".join(
+    [x.read_text(encoding="utf-8") for x in pathlib.Path(shared).glob("*.rst")]
+)
+
+extlinks = {
+    "yadism": ("https://n3pdf.github.io/yadism/%s", "yadism"),
+    "banana": ("https://n3pdf.github.io/banana/%s", "banana"),
+    "pineappl": ("https://n3pdf.github.io/pineappl/%s", "pineappl"),
+    "eko": ("https://github.com/N3PDF/eko/%s", "eko"),
+}
+# -- 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 = []
+
+html_css_files = [
+    'site.css',
+]

docs/source/index.rst

@@ -0,0 +1,58 @@
+.. pineko documentation master file, created by
+   sphinx-quickstart on Thu May 19 12:37:23 2022.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+*****************************
+`pineko` = `PineAPPL` + `eko`
+*****************************
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Overview:
+    :hidden:
+
+    overview/prerequisites
+    overview/running
+    overview/examples
+    overview/indices
+
+.. toctree::
+    :maxdepth: 1
+    :caption: Theory:
+    :hidden:
+
+    theory/fktables
+    theory/scalevar
+
+
+    zzz-refs
+
+**pineko** converts
+
+- interpolation grids for theory predictions (*grids* for short) in the form of
+  |pineappl| grids, together with
+- |EKO| generated by |eko|
+
+into fast-kernel (**FK**) tables. The collection of all FK tables constitute the
+theory predictions for a PDF fit and therefore is often simply called *theory*.
+
+*pineko* is:
+
+* open-source since the beginning - allowing a community effort for writing a new generation of code
+
+* written in Python - opting for a popular, high-level langauge to facilitate other authors to participate in the project
+
+* part of the N3PDF software compendium: |eko|, |banana|, |pineappl| and |yadism| 
+
+`pineko` replaces `APFELcomb <https://github.com/NNPDF/apfelcomb/>`_ , which was
+used up to NNPDF4.0.
+
+
+
+
+
+
+
+
+

docs/source/overview/Prerequisites.rst

@@ -0,0 +1,67 @@
+#############
+Prerequisites
+#############
+
+Generating a *theory*, as defined above, requires several files which are
+described next.
+
+*pineko.toml*
+-------------
+
+You need to provide a *pineko.toml*, that provides all necessary paths to the input and output folders.
+[**DEBUG**: Look at the **DEBUG** example in this repo [1]_.]
+
+*ymldb*
+-------
+
+You need all files of the *ymldb* [2]_.  [**DEBUG**: Look at the respective *load.sh* script to load from dom.]
+This defines the mapping from datasets to FK tables.
+
+Theory Runcards
+---------------
+
+You need to provide the necessary theory runcards named with their respective theory ID inside the *paths.theory_cards* folder [3]_.
+
+Default Operator Card
+---------------------
+
+You need to provide a default operator card for |EKO| [4]_.
+[**DEBUG**: Look at the respective *load.sh* script to load from dom.]
+
+Grids
+-----
+
+*pineko* does **NOT** compute grids, which are instead expected input to *pineko*.
+There are typically two ways to obtain grids: computing them from scratch with `runcards <https://github.com/NNPDF/runcards/>`_
+or reusing existing ones.
+
+Generate new Grids with *rr*
+""""""""""""""""""""""""""""
+
+You need to run *rr* with a given theory runcard and put the generated grid file with the same name
+inside the *paths.grids/theory_id* folder. The name has to match the *ymldb* which is the case by default.
+
+Inherit Grids from Existing Theory
+""""""""""""""""""""""""""""""""""
+
+You can reuse the grids from a different theory by running:: 
+
+  pineko theory inherit-grids SOURCE_THEORY_ID TARGET_THEORY_ID DATASET1 DATASET2 ...
+
+The relation between the source theory and the target theory is non-trivial [5]_.
+
+
+Notes
+-----
+
+.. [1] Actually, instead we should provide a concise description here - but let's wait to be stable first
+
+.. [2] this is to be replaced by the new CommonData format
+
+.. [3] this is to be replaced by a binding to the true theory DB
+
+.. [4] I'm thinking how to improve this, because how could we provide a study on the interpolation accuracy? at the moment there just equal
+
+.. [5] examples being SV, different evolution settings, etc.
+
+

docs/source/overview/examples.rst

@@ -0,0 +1,6 @@
+Examples
+========
+
+In this section some examples on how actually pineko can be used in 
+several situation are provided. 
+

docs/source/overview/indices.rst

@@ -0,0 +1,6 @@
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`