add documentation

Documentation built with Sphinx and hosted at github.io.

---------

Co-authored-by: avellino <[email protected]>

Author: prohde

.gitignore

@@ -14,4 +14,5 @@ venv/
 
 DeTrusty/Sparql/Parser/parsetab.py
 
-.decompositions.log
+.decompositions.log
+.rdfmts.log

DeTrusty/Molecule/MTCreation.py

@@ -58,6 +58,28 @@ def get_params(self):
 def create_rdfmts(endpoints: list | dict,
                   output: Optional[str] = DEFAULT_OUTPUT_PATH,
                   interlinking: bool = False) -> Optional[JSONConfig]:
+
+    """Generating rdfmts.json, which need to be supplied during query execution using run_query
+
+    Parameters
+    ----------
+    endpoints : list or dict
+        The endpoints, from which informations will be collected.
+    output : str, optional
+        Path location in which the generated configuration will be saved. 
+
+        * In case of not supplied: default path will be used, i.e. path/to/DeTrusty-installation/Config/rdfmts.json'
+        * In case of None is supplied: the config won't be saved, instead JSONConfig files will be returned.
+
+    interlinking : bool, optional
+        When supplied with True, the module will assume that there's an interlinks between endpoints, and thus generating configuration that suits this purpose. Default value is False.
+
+    Return
+    ------
+    JSONConfig, optional
+        only generating return value when output=None.
+
+    """
     logger_wrapper = get_logger('DeTrusty.Wrapper.RDFWrapper')
     logger_wrapper.setLevel(logging.WARNING)  # temporarily disable logging of contacting the source
 

DeTrusty/Molecule/MTManager.py

@@ -13,6 +13,39 @@
 
 
 def get_config(config_input: str | list[dict]):
+    """Creates an object with the internal representation of the source descriptions.
+
+    Based on the type of input, this function will create a ``Config`` object either
+    from a local file, remote file, or a list of dictionaries. The source descriptions
+    are later used by DeTrusty for the source selection and decomposition. The main
+    usage of this function is to read stored source descriptions from a file (local or remote)
+    in order to reuse them for query execution over the same federation.
+
+    Parameters
+    ----------
+    config_input: str | list[dict]
+        The source description to transform into the internal representation. Might be a string holding the path
+        to a configuration file. The configuration file can be local or remote (accessible via GET request).
+        The source description can also be a parsed JSON, i.e., a list of Python dictionaries. Each dictionary
+        represents a so-called *RDF Molecule Template*.
+
+    Returns
+    -------
+    Config
+        The object holding the internal representation of the source descriptions. The result might be ``None``
+        if there was an issue while reading the source descriptions that did not lead to an exception.
+
+    Examples
+    --------
+    The example calls assume that the file ``rdftms.json`` is a valid source description file created by DeTrusty.
+    See `Creating Source Descriptions <https://sdm-tib.github.io/DeTrusty/library.html#creating-source-descriptions>`_
+    for more information.
+
+    >>> get_config('./rdfmts.json')
+
+    >>> get_config('http://example.com/rdfmts.json')
+
+    """
     if isinstance(config_input, list):
         return JSONConfig(config_input)
     else:
@@ -167,11 +200,15 @@ def saveToFile(self, path):
 
 class ConfigFile(Config):
     def __init__(self, configfile):
+        self.orig_file = configfile
         if os.path.isfile(configfile):
             super().__init__(configfile=configfile)
         else:
             super().__init__()
 
+    def __repr__(self):
+        return 'ConfigFile(' + str(self.orig_file) + ')'
+
     def getAll(self):
         return self.read_json_file(self.configfile)
 

DeTrusty/__init__.py

@@ -64,6 +64,16 @@ def run_query(query: str,
         It returns an error message in the 'error' field if something went wrong. Other metadata might
         be omitted in that case.
 
+    Examples
+    --------
+    The example calls assume that an object ``config`` with the source descriptions exists.
+
+    >>> run_query('SELECT ?s WHERE { ?s a <http://example.com/Person> }', config=config)
+
+    >>> run_query('./query.rq', config=config)
+
+    >>> run_query('http://example.com/queries/query.rq', config=config)
+
     """
     start_time = time.time()
     decomposer = Decomposer(get_query_string(query), config,