add doc/descriptions

README.md

@@ -1,6 +1,6 @@
 # cmem-plugin-shapes
 
-An [eccenca](https://eccenca.com) [Corporate Memory](https://documentation.eccenca.com) workflow plugin generating SHACL node and property shapes from data graphs.
+Generate SHACL node and property shapes from a data graph.
 
 [![eccenca Corporate Memory](https://img.shields.io/badge/eccenca-Corporate%20Memory-orange)](https://documentation.eccenca.com) [![workflow](https://github.com/eccenca/cmem-plugin-shapes/actions/workflows/check.yml/badge.svg)](https://github.com/eccenca/cmem-plugin-pyshacl/actions) [![pypi version](https://img.shields.io/pypi/v/cmem-plugin-shapes)](https://pypi.org/project/cmem-plugin-shapes/) [![license](https://img.shields.io/pypi/l/cmem-plugin-shapes)](https://pypi.org/project/cmem-plugin-shapes)
 
@@ -9,24 +9,23 @@ An [eccenca](https://eccenca.com) [Corporate Memory](https://documentation.eccen
 
 ### Data graph
 
-The IRI of the data graph to be analyzed.
+The input data graph to be analyzed for the SHACL shapes generation.
 
-### SHACL shapes graph
+### Output SHACL shapes graph
 
-The IRI of the SHACL graph to be produced.
+The output SHACL shapes graph.
 
 ### Overwrite shapes graph if it exists
 
-If enabled and a graph with the specified SHACL shapes graph IRI exists, the graph will be
-overwritten with the result. If disabled and such a graph exists, the plugin execution fails.
+Overwrite the output SHACL shapes graph if it exists. If disabled and the graph exists, the plugin execution fails.
 
 ### Import shapes graph in CMEM Shapes Catalog
 
-If enabled, the resulting SHACL shapes graph is imported with `owl:imports` in the CMEM Shapes Catalog.
+Import the SHACL shapes graph in the CMEM Shapes catalog by adding an `owl:imports` statement to the CMEM Shapes Catalog.
 
-### Fetch namespace prefixes from prefix.cc
+### Use prefixes
 
-If enabled, attempt to fetch namespace prefixes from [http://prefix.cc](http://prefix.cc) instead of from the local database.
+Attempt to fetch namespace prefixes from [http://prefix.cc](http://prefix.cc) instead of from the local database.
 If this fails, fall back on local database.
 
 

cmem_plugin_shapes/doc/__init__.py

@@ -0,0 +1,6 @@
+"""doc"""
+
+from pathlib import Path
+
+with (Path(__path__[0]) / "shapes_doc.md").open("r", encoding="utf-8") as f:
+    SHAPES_DOC = f.read()

cmem_plugin_shapes/doc/shapes_doc.md

@@ -0,0 +1,24 @@
+A task generating SHACL node and property shapes from a data graph.
+
+## Parameters
+
+### Data graph
+
+The input data graph to be analyzed for the SHACL shapes generation.
+
+### Output SHACL shapes graph
+
+The output SHACL shapes graph.
+
+### Overwrite shapes graph if it exists
+
+Overwrite the output SHACL shapes graph if it exists. If disabled and the graph exists, the plugin execution fails.
+
+### Import shapes graph in CMEM Shapes Catalog
+
+Import the SHACL shapes graph in the CMEM Shapes catalog by adding an `owl:imports` statement to the CMEM Shapes Catalog.
+
+### Use prefixes
+
+Attempt to fetch namespace prefixes from [http://prefix.cc](http://prefix.cc) instead of from the local database.
+If this fails, fall back on local database.

cmem_plugin_shapes/plugin_shapes.py

@@ -28,6 +28,8 @@
 from urllib3.exceptions import InsecureRequestWarning
 from validators import url
 
+from cmem_plugin_shapes.doc import SHAPES_DOC
+
 from . import __path__
 
 environ["SSL_VERIFY"] = "false"
@@ -44,14 +46,14 @@ def format_namespace(iri: str) -> str:
 @Plugin(
     label="Generate SHACL shapes from data",
     icon=Icon(file_name="shacl.jpg", package=__package__),
-    description="Generates SHACL node and property shapes from a data graph",
-    documentation="",
+    description="Generate SHACL node and property shapes from a data graph",
+    documentation=SHAPES_DOC,
     parameters=[
         PluginParameter(
             param_type=GraphParameterType(),
             name="data_graph_iri",
             label="Input data graph.",
-            description="",
+            description="The input data graph to be analyzed for the SHACL shapes generation.",
         ),
         PluginParameter(
             param_type=GraphParameterType(
@@ -60,28 +62,30 @@ def format_namespace(iri: str) -> str:
             ),
             name="shapes_graph_iri",
             label="Output SHACL shapes graph.",
-            description="",
+            description="The output SHACL shapes graph.",
         ),
         PluginParameter(
             param_type=BoolParameterType(),
             name="overwrite",
-            label="Overwrite shapes graph if it exists.",
-            description="",
+            label="Overwrite output graph.",
+            description="""Overwrite the output SHACL shapes graph if it exists. If disabled and
+            the graph exists, the plugin execution fails.""",
             default_value=False,
         ),
         PluginParameter(
             param_type=BoolParameterType(),
             name="import_shapes",
-            label="Import shapes graph in CMEM Shapes Catalog.",
-            description="",
+            label="Import SHACL shapes graph in CMEM Shapes Catalog.",
+            description="""Import the SHACL shapes graph in the CMEM Shapes catalog by adding an
+            `owl:imports` triple to the CMEM Shapes Catalog.""",
             default_value=False,
         ),
         PluginParameter(
             param_type=BoolParameterType(),
             name="prefix_cc",
-            label="Fetch namespace prefixes from prefix.cc.",
-            description="""If enabled, attempt to fetch namespace prefixes from http://prefix.cc
-            instead of from the local database. If this fails, fall back on local database.""",
+            label="Fetch namespace prefixes from prefix.cc",
+            description="""IAttempt to fetch namespace prefixes from http://prefix.cc instead of
+            from the local database. If this fails, fall back on local database.""",
             default_value=True,
             advanced=True,
         ),