Link to semantic terms for each field in documentation

trompamusic · Jun 14, 2021 · 4951669 · 4951669
1 parent 941bdfa
commit 4951669
Show file tree

Hide file tree

Showing 4 changed files with 54 additions and 49 deletions.
diff --git a/docs/conf.py b/docs/conf.py
@@ -26,7 +26,7 @@
 # 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.napoleon', 'sphinx.ext.autosectionlabel']
+extensions = ['sphinx.ext.autodoc', 'sphinx.ext.napoleon', 'sphinx.ext.autosectionlabel', 'sphinx.ext.extlinks']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -36,6 +36,10 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
+extlinks = {'schema': ('https://schema.org/%s', 'schema:'),
+            'dcterms': ('http://purl.org/dc/terms/%s', 'dcterms:')
+            }
+
 
 # -- Options for HTML output -------------------------------------------------
 

diff --git a/docs/mutations/person.rst b/docs/mutations/person.rst
@@ -1,40 +1,41 @@
 Person
 ======
 
-A ``Person`` objects represents a web resource about a person. For example, this could be a composer or performer.
-
-We recommend that the following fields are set:
-
-.. csv-table::
-   :header: "field", "required", "Description"
-   :stub-columns: 1
-
-   `title <http://purl.org/dc/elements/1.1/title>`_, yes, The title of the resource indicated by ``source``
-   contributor, yes,The main URL of the site where the information about this Person was taken from
-   creator, yes, "The person, organization or service who is creating this Person (e.g. URL of the software)"
-   source, yes, The URL of the web resource where information about this Person is taken from
-   language, yes, "The language the metadata is written in. Currently supported languages are en,es,ca,nl,de,fr"
-   format\_, yes, The mimetype of the resource indicated by `source`
-   name, yes, The name of the person
-   family_name, , The family name of the person
-   given_name, , The given name of the person
-   gender, , The person's gender
-   birth_date, , "The birth date of the person, formatted as yyyy, yyyy-mm or yyyy-mm-dd"
-   death_date, , "The date of death of the person , formatted as yyyy, yyyy-mm or yyyy-mm-dd"
-   description, , A biographical description of the person
-   image, , URL to an image associated with the person
-   publisher, , An entity responsible for making the resource available
-   honorific_prefix, , An honorific prefix
-   honorific_suffix, , An honorific suffix
-   job_title, , The person's job title
+A :schema:`Person` object represents a web resource about a person. For example, this could be a composer or performer.
+
+
+Creating objects
+----------------
+
+To create a ``Person`` object, use the ``CreatePerson`` mutation
+
+.. autofunction:: trompace.mutations.person.mutation_create_person
+
+To update a ``Person`` object, use the ``UpdatePerson`` mutation
+
+.. autofunction:: trompace.mutations.person.mutation_update_person
+
+To delete a ``Person`` object, use the ``DeletePerson`` mutation
+
+.. autofunction:: trompace.mutations.person.mutation_delete_person
 
 
 Relations
 ---------
 
-exactMatch: Use :meth:`trompace.mutations.person.mutation_person_add_exact_match_person`
+exactMatch
+^^^^^^^^^^
+
+The `skos:exactMatch <http://www.w3.org/2004/02/skos/core#exactMatch>`_ relationship is used to identify
+that two ``Person`` nodes refer to the exact same natural person.
+
+.. image:: ../graphics/x.png
+  :target: ../_images/x.png
+
+Use the ``MergePersonExactMatch`` mutation to create a one-way link between two ``Person`` objects
 
+.. autofunction:: trompace.mutations.person.mutation_person_add_exact_match_person
 
+Use the ``RemovePersonExactMatch`` mutation to remove link between two ``Person`` objects
 
-.. automodule:: trompace.mutations.person
-   :members:
+.. autofunction:: trompace.mutations.person.mutation_person_remove_exact_match_person
diff --git a/setup.py b/setup.py
@@ -10,7 +10,7 @@
     description="A python library to read from and write to the Trompa CE",
     long_description=long_description,
     long_description_content_type="text/markdown",
-    url="https://github.com/trompamusic/trompa-ce-client",
+    url="https://github.com/trompamusic/trompace-client",
     packages=find_packages(exclude=['tests', 'demo']),
     use_scm_version=True,
     setup_requires=['setuptools_scm'],

diff --git a/trompace/mutations/person.py b/trompace/mutations/person.py
@@ -5,24 +5,24 @@
 from trompace import StringConstant, _Neo4jDate, check_required_args, filter_none_args, docstring_interpolate
 from trompace.constants import SUPPORTED_LANGUAGES, SUPPORTED_GENDER
 
-PERSON_ARGS_DOCS = """title: The title of the resource indicated by `source`
-        contributor: The main URL of the site where the information about this Person was taken from
-        creator: The person, organization or service who is creating this Person (e.g. URL of the software)
-        source: The URL of the web resource where information about this Person is taken from
-        language: The language the metadata is written in. Currently supported languages are en,es,ca,nl,de,fr
-        format_: The mimetype of the resource indicated by `source`
-        name: The name of the person
-        family_name (optional): The family name of the person
-        given_name (optional): The given name of the person
-        gender (optional): The person's gender
-        birth_date (optional): The birth date of the person, formatted as yyyy, yyyy-mm or yyyy-mm-dd
-        death_date (optional): The date of death of the person , formatted as yyyy, yyyy-mm or yyyy-mm-dd
-        description (optional): A biographical description of the person
-        image (optional): URL to an image associated with the person
-        publisher (optional): An entity responsible for making the resource available
-        honorific_prefix (optional): An honorific prefix.
-        honorific_suffix (optional): An honorific suffix.
-        job_title (optional): The person's job title."""
+PERSON_ARGS_DOCS = """title: The title of the resource indicated by `source` (:dcterms:`title`)
+        contributor: The main URL of the site where the information about this Person was taken from (:dcterms:`contributor`)
+        creator: The person, organization or service who is creating this Person (e.g. URL of the software) (:dcterms:`creator`)
+        source: The URL of the web resource where information about this Person is taken from (:dcterms:`source`)
+        language: The language the metadata is written in. Currently supported languages are en,es,ca,nl,de,fr (:dcterms:`language`)
+        format_: The mimetype of the resource indicated by `source` (:dcterms:`format`)
+        name: The name of the person (:schema:`name`)
+        family_name (optional): The family name of the person (:schema:`familyName`)
+        given_name (optional): The given name of the person (:schema:`givenName`)
+        gender (optional): The person's gender (:schema:`gender`)
+        birth_date (optional): The birth date of the person, formatted as yyyy, yyyy-mm or yyyy-mm-dd (:schema:`birthDate`)
+        death_date (optional): The date of death of the person , formatted as yyyy, yyyy-mm or yyyy-mm-dd (:schema:`deathDate`)
+        description (optional): A biographical description of the person (:dcterms:`description`)
+        image (optional): URL to an image associated with the person (:schema:`image`)
+        publisher (optional): An entity responsible for making the resource available (:dcterms:`publisher`)
+        honorific_prefix (optional): An honorific prefix (:schema:`honorificPrefix`)
+        honorific_suffix (optional): An honorific suffix (:schema:`honorificSuffix`)
+        job_title (optional): The person's job title. (:schema:`jobTitle`)"""
 
 
 @docstring_interpolate("person_args", PERSON_ARGS_DOCS)