Documentation rework that plugins usage and modules are crosslinked (#3320)

* Reworked description for all modules, that are linked as plugin description. Added crosslink for plugin related things. linked: Graph.serialize - rdflib.plugins.serializers; Graph.parse - rdflib.plugins.parsers; Result.serialize - rdflib.plugins.sparql.results; Graph.__init__ - rdflib.plugins.stores;

* add apostrophe

---------

Co-authored-by: Nicholas Car <[email protected]>
Co-authored-by: Nicholas Car <[email protected]>

Author: WhiteGobo

rdflib/graph.py

@@ -476,30 +476,40 @@ class Graph(Node):
 
         ```
 
-    !!! info "Graph stores"
-        The constructor accepts one argument, the "store" that will be used to store the
-        graph data with the default being the [`Memory`][rdflib.plugins.stores.memory.Memory]
-        (in memory) Store. Other Stores that persist content to disk using various file
-        databases or Stores that use remote servers (SPARQL systems) are supported. See
-        the `rdflib.plugins.stores` package for Stores currently shipped with RDFLib.
-        Other Stores not shipped with RDFLib can be added, such as
-        [HDT](https://github.com/rdflib/rdflib-hdt/).
-
-        Stores can be context-aware or unaware. Unaware stores take up
-        (some) less space but cannot support features that require
-        context, such as true merging/demerging of sub-graphs and
-        provenance.
-
-        Even if used with a context-aware store, Graph will only expose the quads which
-        belong to the default graph. To access the rest of the data the
-        `Dataset` class can be used instead.
-
-        The Graph constructor can take an identifier which identifies the Graph
-        by name. If none is given, the graph is assigned a BNode for its
-        identifier.
-
-        For more on Named Graphs, see the RDFLib `Dataset` class and the TriG Specification,
-        <https://www.w3.org/TR/trig/>.
+
+    Args:
+        store: The constructor accepts one argument, the "store" that will be used to store the
+            graph data with the default being the [`Memory`][rdflib.plugins.stores.memory.Memory]
+            (in memory) Store. Other Stores that persist content to disk using various file
+            databases or Stores that use remote servers (SPARQL systems) are supported.
+            All [builtin storetypes][rdflib.plugins.stores] can be accessed via
+            their registered names.
+            Other Stores not shipped with RDFLib can be added as plugins, such as
+            [HDT](https://github.com/rdflib/rdflib-hdt/).
+            Registration of external plugins
+            is described in [`rdflib.plugin`][rdflib.plugin].
+
+            Stores can be context-aware or unaware. Unaware stores take up
+            (some) less space but cannot support features that require
+            context, such as true merging/demerging of sub-graphs and
+            provenance.
+
+            Even if used with a context-aware store, Graph will only expose the quads which
+            belong to the default graph. To access the rest of the data the
+            `Dataset` class can be used instead.
+
+            The Graph constructor can take an identifier which identifies the Graph
+            by name. If none is given, the graph is assigned a BNode for its
+            identifier.
+
+            For more on Named Graphs, see the RDFLib `Dataset` class and the TriG Specification,
+            <https://www.w3.org/TR/trig/>.
+        identifier: identifier of the graph itself
+        namespace_manager: Used namespace manager.
+            Create with bind_namespaces if `None`.
+        base: Base used for [URIs][rdflib.term.URIRef]
+        bind_namespaces: Used bind_namespaces for namespace_manager
+            Is only used, when no namespace_manager is provided.
     """
 
     context_aware: bool
@@ -1450,9 +1460,11 @@ def serialize(
                 string or pathlib.PurePath object, or it can be an IO[bytes] like object.
                 If this parameter is not supplied the serialized graph will be returned.
             format: The format that the output should be written in. This value
-                references a Serializer plugin. Format support can be extended with plugins,
-                but "xml", "n3", "turtle", "nt", "pretty-xml", "trix", "trig", "nquads",
-                "json-ld" and "hext" are built in. Defaults to "turtle".
+                references a Serializer plugin.
+                Format support is managed with [plugins][rdflib.plugin].
+                Defaults to "turtle" and some other formats are builtin,
+                like "xml" and "trix".
+                See also [serialize module][rdflib.plugins.parsers].
             base: The base IRI for formats that support it. For the turtle format this
                 will be used as the @base directive.
             encoding: Encoding of output.
@@ -1539,9 +1551,10 @@ def parse(
                 RFC 3986 <https://datatracker.ietf.org/doc/html/rfc3986#section-5.1.4>`_,
                 given the source document does not define a base URI.
             format: Used if format can not be determined from source, e.g.
-                file extension or Media Type. Defaults to text/turtle. Format
-                support can be extended with plugins, but "xml", "n3" (use for
-                turtle), "nt" & "trix" are built in.
+                file extension or Media Type. Format support is managed
+                with [plugins][rdflib.plugin].
+                Available formats are e.g. "turle", "xml", "n3", "nt" and "trix"
+                or see [parser module][rdflib.plugins.parsers].
             location: A string indicating the relative or absolute URL of the
                 source. `Graph`'s absolutize method is used if a relative location
                 is specified.

rdflib/plugins/parsers/__init__.py

@@ -1,3 +1,8 @@
-"""
+"""Module for builtin RDF parser
+
+All builtin [RDF parser][rdflib.parser.Parser] available
+in [RDFLib Graphs method `parse`][rdflib.graph.Graph.parse] are listed here.
 
+Registration of builtin and external plugins
+is described in [`rdflib.plugin`][rdflib.plugin].
 """

rdflib/plugins/serializers/__init__.py

@@ -0,0 +1,8 @@
+"""Module for builtin RDF Serializer.
+
+All builtin [RDF serializer][rdflib.serializer.Serializer] available
+in [RDFLib Graphs method `serialize`][rdflib.graph.Graph.serialize] are listed here.
+
+Registration of builtin and external plugins
+is described in [`rdflib.plugin`][rdflib.plugin].
+"""

rdflib/plugins/sparql/results/__init__.py

@@ -1,3 +1,21 @@
-"""
-Parsers and serializers for SPARQL Result formats
+"""Parsers and serializers for SPARQL Result formats
+
+All builtin [SPARQL result serializers][rdflib.query.ResultSerializer] available
+after [a query][rdflib.graph.Graph.query] are listed here.
+The serializer can be chosen during [serialization of a result][rdflib.query.Result.serialize].
+
+```
+import rdflib
+
+result : rdflib.query.Result
+g = rdflib.Graph().parse(format="ttl", data=\"\"\"
+    @base <http://example.org/> .
+    <MyObject> a <MyClass>.
+\"\"\")
+result = g.query("SELECT ?x ?cls WHERE {?x a ?cls}")
+print(result.serialize(format="txt").decode("utf8"))
+```
+
+Registration of builtin and external plugins
+is described in [`rdflib.plugin`][rdflib.plugin].
 """

rdflib/plugins/stores/__init__.py

@@ -1,3 +1,8 @@
-"""
-This package contains modules for additional RDFLib stores
+"""Module for builtin RDF stores.
+
+All builtin [RDF Stores][rdflib.store.Store] available
+during [RDFLib Graphs creation][rdflib.graph.Graph] are listed here.
+
+Registration of builtin and external plugins
+is described in [`rdflib.plugin`][rdflib.plugin].
 """

rdflib/query.py

@@ -283,20 +283,25 @@ def serialize(
         """
         Serialize the query result.
 
-        The `format` argument determines the Serializer class to use.
-
-        - csv: [`CSVResultSerializer`][rdflib.plugins.sparql.results.csvresults.CSVResultSerializer]
-        - json: [`JSONResultSerializer`][rdflib.plugins.sparql.results.jsonresults.JSONResultSerializer]
-        - txt: [`TXTResultSerializer`][rdflib.plugins.sparql.results.txtresults.TXTResultSerializer]
-        - xml: [`XMLResultSerializer`][rdflib.plugins.sparql.results.xmlresults.XMLResultSerializer]
 
         Args:
-            destination: Path of file output or BufferedIOBase object to write the output to.
+            destination: Path of file output or BufferedIOBase object
+                to write the output to. If `None` this function
+                will return the output as  `bytes`
             encoding: Encoding of output.
-            format: One of ['csv', 'json', 'txt', xml']
+            format: The format used for serialization.
+                See [sparql.results module][rdflib.plugins.sparql.results]
+                for all builtin SPARQL result serialization.
+                Further serializer can be loaded [as plugin][rdflib.plugin].
+                Some example formats are
+                [csv][rdflib.plugins.sparql.results.csvresults.CSVResultSerializer],
+                [json][rdflib.plugins.sparql.results.jsonresults.JSONResultSerializer],
+                [txt][rdflib.plugins.sparql.results.txtresults.TXTResultSerializer]
+                or
+                [xml][rdflib.plugins.sparql.results.xmlresults.XMLResultSerializer]
 
         Returns:
-            bytes
+            Serialized result, when destination is not given.
         """
         if self.type in ("CONSTRUCT", "DESCRIBE"):
             # type error: Item "None" of "Optional[Graph]" has no attribute "serialize"

rdflib/serializer.py

@@ -1,11 +1,14 @@
 """Serializer plugin interface.
 
-This module is useful for those wanting to write a serializer that can
-plugin to rdflib. If you are wanting to invoke a serializer you likely
-want to do so through the Graph class serialize method.
+The RDF serialization plugins used during
+[RDFlib's common serialization of a graph][rdflib.graph.Graph.serialize]
+is described in this module.
 
 TODO: info for how to write a serializer that can plugin to rdflib.
 See also [`rdflib.plugin`][rdflib.plugin]
+
+All builtin RDF Serializer are listed
+under [`rdflib.plugins.serializers`][rdflib.plugins.serializers].
 """
 
 from __future__ import annotations
@@ -24,6 +27,12 @@
 
 
 class Serializer:
+    """Base class for RDF Serializer.
+
+    New Serializer can be registered as plugin as described
+    in [`rdflib.plugin`][rdflib.plugin].
+    """
+
     def __init__(self, store: Graph):
         self.store: Graph = store
         self.encoding: str = "utf-8"
@@ -36,7 +45,17 @@ def serialize(
         encoding: Optional[str] = None,
         **args: Any,
     ) -> None:
-        """Abstract method"""
+        """Abstract method. Print [Graph][rdflib.graph.Graph].
+        Used in [Graph.serialize][rdflib.graph.Graph.serialize]
+
+        Serialize Graph
+
+        Args:
+            stream: The destination to serialize the graph to.
+            base: The base IRI for formats that support it.
+            encoding: Encoding of output.
+            args: Additional arguments to pass to the Serializer that will be used.
+        """
 
     def relativize(self, uri: _StrT) -> Union[_StrT, URIRef]:
         base = self.base