workaround line_num bug for decorators in apidocs

docs/ref.md

@@ -14,33 +14,6 @@ Core feature areas include:
   * SHACL validation
   * inference based on OWL-RL, RDFS, SKOS
 
----
-#### [`load_rdf` method](#kglab.KnowledgeGraph.load_rdf)
-[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/decorators.py#L58)
-
-```python
-load_rdf(path, format="ttl", base=None, **args)
-```
-Wrapper for [`rdflib.Graph.parse()`](https://rdflib.readthedocs.io/en/stable/apidocs/rdflib.html#rdflib.graph.Graph.parse) which parses an RDF graph from the `path` source.
-This traps some edge cases for the several source-ish parameters in RDFlib which had been overloaded.
-Throws `TypeError` whenever a format parser plugin encounters a syntax error.
-
-Note: this adds relations to an RDF graph, although it does not overwrite the existing RDF graph.
-
-  * `path` : `typing.Union[str, pathlib.Path, urlpath.URL, typing.IO]`  
-must be a file name (str) to a local file reference – possibly a glob with a wildcard; or a path object (not a URL) to a local file reference; or a [*readable, file-like object*](https://docs.python.org/3/glossary.html#term-file-object); otherwise this throws a `TypeError` exception
-
-  * `format` : `str`  
-serialization format, defaults to Turtle triples; see `_RDF_FORMAT` for a list of default formats, which can be extended with plugins – excluding the `"json-ld"` format; otherwise this throws a `TypeError` exception
-
-  * `base` : `str`  
-logical URI to use as the document base; if not specified, the document location gets used
-
-  * *returns* : `KnowledgeGraph`  
-this `KnowledgeGraph` object – used for method chaining
-
-
-
 ---
 #### [`__init__` method](#kglab.KnowledgeGraph.__init__)
 [*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L67)
@@ -235,6 +208,33 @@ To prepare for upcoming **kglab** features, **this is the preferred method for r
 
 
 
+---
+#### [`load_rdf` method](#kglab.KnowledgeGraph.load_rdf)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/decorators.py#L58)
+
+```python
+load_rdf(path, format="ttl", base=None, **args)
+```
+Wrapper for [`rdflib.Graph.parse()`](https://rdflib.readthedocs.io/en/stable/apidocs/rdflib.html#rdflib.graph.Graph.parse) which parses an RDF graph from the `path` source.
+This traps some edge cases for the several source-ish parameters in RDFlib which had been overloaded.
+Throws `TypeError` whenever a format parser plugin encounters a syntax error.
+
+Note: this adds relations to an RDF graph, although it does not overwrite the existing RDF graph.
+
+  * `path` : `typing.Union[str, pathlib.Path, urlpath.URL, typing.IO]`  
+must be a file name (str) to a local file reference – possibly a glob with a wildcard; or a path object (not a URL) to a local file reference; or a [*readable, file-like object*](https://docs.python.org/3/glossary.html#term-file-object); otherwise this throws a `TypeError` exception
+
+  * `format` : `str`  
+serialization format, defaults to Turtle triples; see `_RDF_FORMAT` for a list of default formats, which can be extended with plugins – excluding the `"json-ld"` format; otherwise this throws a `TypeError` exception
+
+  * `base` : `str`  
+logical URI to use as the document base; if not specified, the document location gets used
+
+  * *returns* : `KnowledgeGraph`  
+this `KnowledgeGraph` object – used for method chaining
+
+
+
 ---
 #### [`load_rdf_text` method](#kglab.KnowledgeGraph.load_rdf_text)
 [*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L522)
@@ -308,6 +308,29 @@ text representing the RDF graph
 
 
 
+---
+#### [`load_jsonld` method](#kglab.KnowledgeGraph.load_jsonld)
+[*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/decorators.py#L58)
+
+```python
+load_jsonld(path, encoding="utf-8", **args)
+```
+Wrapper for [`rdflib-jsonld.parser.JsonLDParser.parse()`](https://github.com/RDFLib/rdflib-jsonld/blob/master/rdflib_jsonld/parser.py) which parses an RDF graph from a [JSON-LD](https://json-ld.org/) source.
+This traps some edge cases for the several source-ish parameters in RDFlib which had been overloaded.
+
+Note: this adds relations to an RDF graph, it does not overwrite the existing RDF graph.
+
+  * `path` : `typing.Union[str, pathlib.Path, urlpath.URL, typing.IO]`  
+must be a file name (str) to a local file reference – possibly a glob with a wildcard; or a path object (not a URL) to a local file reference; or a [*readable, file-like object*](https://docs.python.org/3/glossary.html#term-file-object)
+
+  * `encoding` : `str`  
+text encoding value, which defaults to `"utf-8"`; must be in the [Python codec registry](https://docs.python.org/3/library/codecs.html#codecs.CodecInfo); otherwise this throws a `LookupError` exception
+
+  * *returns* : `KnowledgeGraph`  
+this `KnowledgeGraph` object – used for method chaining
+
+
+
 ---
 #### [`save_jsonld` method](#kglab.KnowledgeGraph.save_jsonld)
 [*\[source\]*](https://github.com/DerwenAI/kglab/blob/main/kglab/kglab.py#L714)

pyfixdoc.py

@@ -435,6 +435,36 @@ def document_type (
         return local_md
 
 
+    @classmethod
+    def find_line_num (
+        cls,
+        src: typing.Tuple[typing.List[str], int],
+        member_name: str,
+        ) -> int:
+        """
+Corrects for the error in parsing source line numbers of class methods that have decorators:
+<https://stackoverflow.com/questions/8339331/how-to-get-line-number-of-function-with-without-a-decorator-in-a-python-module>
+
+    src:
+list of source lines for the class being inspected
+
+    member_name:
+name of the class member to locate
+
+    returns:
+corrected line number of the method definition
+        """
+        correct_line_num = -1
+
+        for line_num, line in enumerate(src[0]):
+            tokens = line.strip().split(" ")
+
+            if tokens[0] == "def" and tokens[1] == member_name:
+                correct_line_num = line_num
+
+        return correct_line_num
+
+
     def format_class (
         self,
         todo_list: typing.Dict[ str, typing.Any],
@@ -453,6 +483,7 @@ def format_class (
 
         class_obj = todo_list[class_name]
         docstring = class_obj.__doc__
+        src = inspect.getsourcelines(class_obj)
 
         if docstring:
             # add the raw docstring for a class
@@ -475,7 +506,8 @@ def format_class (
                 else:
                     continue
 
-                line_num, obj_md = self.document_method(path_list, member_name, member_obj, func_kind)
+                _, obj_md = self.document_method(path_list, member_name, member_obj, func_kind)
+                line_num = self.find_line_num(src, member_name)
                 obj_md_pos[line_num] = obj_md
 
         for _, obj_md in sorted(obj_md_pos.items()):