diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..d4bb2cb --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# 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 = . +BUILDDIR = _build + +# 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) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..306430f --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,54 @@ +# 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('.')) + + +# -- Project information ----------------------------------------------------- + +project = 'Information System (IS) Model' +copyright = '2023, Luca Frosini (ISTI-CNR)' +author = 'Luca Frosini (ISTI-CNR)' + +# The full version, including alpha/beta/rc tags +release = '5.0.1-SNAPSHOT' + + +# -- 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 = [] + +# 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'] + + +# -- 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 = 'sphinxdoc' + +# 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'] \ No newline at end of file diff --git a/docs/intro.rst b/docs/intro.rst index e69de29..9d0f858 100644 --- a/docs/intro.rst +++ b/docs/intro.rst @@ -0,0 +1,83 @@ +############################# +Information System (IS) Model +############################# + +This Model is part of research conducted in the context of a PhD. This wiki page represents just a partial view of the full rationale of the research. To have a complete overview of the rationale of the model, please refer to the PhD thesis which is publicly available at: + +https://etd.adm.unipi.it/t/etd-05102019-114151/ + +https://openportal.isti.cnr.it/doc?id=people______::470484e51fcb9e307a418c800efc44c8 + +If you need to refer to such work you can cite the PhD Thesis. + +BibText: + + @phdthesis{frosini2019transactional, + title={Transactional REST Information System for Federated Research Infrastructures enabling Virtual Research Environments}, + author={Frosini, Luca}, + year={2019}, + school={UNIVERSITÀ DI PISA} + } + +An previous paper about this work is: + +BibText: + + @article{frosini2018facet, + title={A Facet-based Open and Extensible Resource Model for Research Data Infrastructures.}, + author={Frosini, Luca and Pagano, Pasquale}, + journal={Grey Journal (TGJ)}, + volume={14}, + number={2}, + year={2018} + } + + + +************ +The IS Model +************ + +The Information System Model (henceforth IS Model) is a graph model with Entities as nodes and Relations as edges. + +* Two typologies of entities are envisaged: + * Resources, i.e. entities representing a description of "thing" to be managed; + * Every Resource is described by a number of Facets. + * Facets, i.e. entities contributing to "build" a description of a Resource. Every facet, once attached to a Resource profile captures a certain aspect / characterization of the resource; + * Every facet is characterised by a number of properties; + +* Two typologies of relations are envisaged: + * IsRelatedTo, i.e. a relation linking any two Resources. + * ConsistsOf, i.e. a relation connecting each Resource with one of the Facets characterizing it; + +* Each entity and relation + * has an header automatically generated for the sake of identification and provenance of the specific information; + * can be specialized + * A number of specializations are identified below. Such specializations are managed by the gCube Core services, i.e. Core services builds upon these specializations to realize its management tasks; + * Other specializations can be defined by clients, the system make it possible to store these additional typologies of relations and facets and to discover them. + +* Facet and Relation instances can have additional properties which are not defined in the schema (henceforth schema-mixed mode). + +* On relations: + * Any relation has a direction, i.e. a "source" (out bound of the relation) and a "target" (in bound of the relation). Anyway, the relation can be also navigated in the opposite direction; + * It is not permitted to define a Relation having a Facet as "source". In other words: + * It is not permitted to define a Relation connecting a Facet with another one; + * It is not permitted to define a Relation connecting a Facet with a Resource (as target); + * A Facet instance can be linked (by ConsistsOf or any specialization of it) from different Resources. + +We derived the term Facet directly from the dictionary definition. +Merriam Webster Dictionary defines facet as “any of the definable aspects that make up a subject +(as of contemplation) or an object (as of consideration)”[1]. + +The Free Dictionary defines a facet as “One of numerous aspects, as of a subject” [2]. + + +.... + +******************************** +IS Model Base Concept Definition +******************************** + +Any extension of the IS Model will be defined as following + + \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 0000000..153be5e --- /dev/null +++ b/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=. +set BUILDDIR=_build + +if "%1" == "" goto help + +%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 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/pom.xml b/pom.xml index b28d521..d74e18c 100644 --- a/pom.xml +++ b/pom.xml @@ -83,4 +83,29 @@ test + + + + + + kr.motd.maven + sphinx-maven-plugin + 2.10.0 + + ${project.build.directory}/${project.artifactId}-${project.version}/docs + html + ${basedir}/docs + ${basedir}/docs + + + + process-resources + + generate + + + + + + \ No newline at end of file