diff --git a/docs/_ext/ld_properties.py b/docs/_ext/ld_properties.py new file mode 100644 --- /dev/null +++ b/docs/_ext/ld_properties.py @@ -0,0 +1,47 @@ +from typing import Any, Dict, List, Tuple + +from docutils.nodes import ( + Element, + Node, + TextElement, + literal, + reference, + system_message, +) +from sphinx.util.docutils import ReferenceRole + +PREFIXES = { + "schema": "http://schema.org/", + "codemeta": "https://codemeta.github.io/terms/", + "forge": "https://forgefed.org/vocabulary.html#", + "as": "https://www.w3.org/TR/activitystreams-vocabulary/#", + "wikidata": "http://www.wikidata.org/entity/", + "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/", +} + + +class PropertyRole(ReferenceRole): + def run(self) -> Tuple[List[Node], List[system_message]]: + (prefix, local_name) = self.target.split(":", 1) + try: + namespace = PREFIXES[prefix] + except KeyError: + msg = self.inliner.reporter.error( + __("invalid prefix %s") % prefix, line=self.lineno + ) + prb = self.inliner.problematic(self.rawtext, self.rawtext, msg) + return [prb], [msg] + + full_name = namespace + local_name + + text = literal("", self.target) + link = reference( + "", "", text, internal=False, refuri=full_name, classes=["ld-property"] + ) + return [link], [] + + +def setup(app: "Sphinx") -> Dict[str, Any]: + from docutils.parsers.rst import roles + + roles.register_local_role("prop", PropertyRole()) diff --git a/docs/conf.py b/docs/conf.py --- a/docs/conf.py +++ b/docs/conf.py @@ -1 +1,7 @@ +import pathlib +import sys + from swh.docs.sphinx.conf import * # NoQA + +sys.path.append(str(pathlib.Path(__file__).parent / "_ext")) +extensions += ["ld_properties"] diff --git a/docs/index.rst b/docs/index.rst --- a/docs/index.rst +++ b/docs/index.rst @@ -14,6 +14,7 @@ README.md dev-info.rst metadata-workflow.rst + mesocore.rst Reference Documentation diff --git a/docs/mesocore.rst b/docs/mesocore.rst new file mode 100644 --- /dev/null +++ b/docs/mesocore.rst @@ -0,0 +1,156 @@ +Metadata on Social Code Repositories +==================================== + +MeSoCoRe is a vocabulary which complements ontologies like schema.org/CodeMeta +and DOAP in describing software projects. While the latter are meant to describe +source code projects, MeSoCoRe describes VCS repositories of these projects. +This includes, for example, "stars" and "watchers" on platforms like GitHub, Gitlab, +or Gitea. + +The namespace is ``https://www.softwareheritage.org/schema/2022/mesocore/``; +and it is meant to be used primarily in alongside CodeMeta/schema.org +and ForgeFed/ActivityStreams. + + +The following prefixes are used throughout this document for readability: + +.. code-block:: json + + { + "schema": "http://schema.org/", + "codemeta": "https://codemeta.github.io/terms/", + "forge": "https://forgefed.org/vocabulary.html#", + "as": "https://www.w3.org/TR/activitystreams-vocabulary/#", + "wikidata": "http://www.wikidata.org/entity/", + "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/", + } + +For example, here is a document using all three together: + +.. code-block:: json + + { + "@context": { + "as": "https://www.w3.org/ns/activitystreams#", + "codemeta": "https://codemeta.github.io/terms/", + "forge": "https://forgefed.org/ns#", + "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/", + "schema":"http://schema.org/", + "wikidata": "http://www.wikidata.org/entity/" + }, + "@type": "forge:Repository", + "@id": "https://github.com/octocat/linguist", + "schema:name": "Linguist", + "schema:description": "Language Savant", + "codemeta:issueTracker": "https://github.com/octocat/linguist/issues", + "mesocore:vcs": { + "@type": "schema:SoftwareApplication", + "@id": "wikidata:Q186055", + "schema:name": "Git" + }, + "mesocore:containsSourceCode": { + "@type": "schema:SoftwareSourceCode", + "schema:name": "Linguist", + "schema:description": "This library is used on GitHub.com to detect blob languages" + }, + "as:followers": { + "@type": "as:OrderedCollection", + "as:totalitems": 123 + }, + "forge:forks": { + "@type": "as:OrderedCollection", + "as:totalItems": 138 + }, + "forge:forkOf": { + "@type": "forge:Repository", + "@id": "https://github.com/github/linguist", + "schema:name": "Linguist" + } + } + + +Types +----- + +*This section is not normative* + +None, MeSoCoRe reuses ``https://forgefed.org/ns#Repository``. + +Relation properties +------------------- + +Relation properties from other specifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*This section is not normative* + +The following properties are typically used in MeSoCoRe documents: + +* The :prop:`as:followers` property lists actors (typically persons) subscribed + to a repository. + As it is an :prop:`as:OrderedCollection`, its :prop:`as:totalItems` attribute contains + the number of followers, which matches ``watchers_count`` on GitHub and GitLab; + which can also be expressed with :prop:`schema:InteractionCounter` +* :prop:`forge:forkedFrom` and :prop:`forge:forks` properties to describe relationships + between repositories. (:prop:`forge:forks` is also an :prop:`as:OrderedCollection`). + +Mirrors +^^^^^^^ + +TODO + +Social properties +----------------- + +Social properties from other specifications +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +*This section is not normative* + +* The :prop:`as:likes` property lists actors (typically persons) who "like" + to a repository. + As it is an :prop:`as:OrderedCollection`, its :prop:`as:totalItems` attribute contains + the number of followers, which matches ``stargazers_count`` on GitHub and + ``star_count`` on GitLab; + which can also be expressed with :prop:`schema:InteractionCounter` + +.. comment: + + * The common concept of star(gazers) and watchers on GitHub/GitLab/Gitea can + be represented using :prop:`schema:InteractionCounter` with types + :prop:`schema:LikeAction` and :prop:`schema:FollowAction` (note that the latter can + also be expressed using :prop:`as:followers`): + TODO: use :prop:`as:likes` instead? + + .. code-block:: json + + { + "@context": { + "as": "https://www.w3.org/ns/activitystreams#", + "codemeta": "https://codemeta.github.io/terms/", + "forge": "https://forgefed.org/ns#", + "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/", + "schema":"http://schema.org/", + "wikidata": "http://www.wikidata.org/entity/" + }, + "@type": "forge:Repository", + "@id": "https://github.com/octocat/linguist", + "schema:interactionStatistic": [ + { + "@type": "schema:InteractionCounter", + "schema:interactionType": "http://schema.org/LikeAction", + "schema:userInteractionCount": 146 + }, + { + "@type": "schema:InteractionCounter", + "schema:interactionType": "http://schema.org/FollowAction", + "schema:userInteractionCount": 123 + }, + ] + } + +Configuration properties +------------------------ + +Statistics properties +---------------------