Update core functions and add docs

Adding docs and continue with testing mkdocs generation

.pre-commit-config.yaml

@@ -3,14 +3,14 @@ repos:
       rev: ''
       hooks:
         - id: black
+    - repo: https://github.com/pre-commit/mirrors-isort
+      rev: ''  # Use the revision sha / tag you want to point at
+      hooks:
+        - id: isort
     - repo: https://github.com/pre-commit/pre-commit-hooks
       rev: ''
       hooks:
         - id: check-added-large-files
-    - repo: https://github.com/pre-commit/mirrors-isort
-      rev: ''  # Use the revision sha / tag you want to point at
-      hooks:
-        -   id: isort
     - repo: local
       hooks:
         - id: pylint

doc-requirements.txt

@@ -0,0 +1,12 @@
+click-man
+mkdocs
+mkdocstrings
+mkdocs-exclude
+mkdocs-macros-plugin
+mkdocs-material
+mkdocs-minify-plugin
+mkdocs-redirects
+mkdocs-git-revision-date-plugin
+pymdown-extensions
+mkdocs-git-revision-date-localized-plugin
+pyspelling

docs/generate_docs.py

@@ -0,0 +1,38 @@
+from pathlib import Path
+
+from mkdocstrings_sourcelink import MkDocGenerator
+
+pages = {
+    "Documentation": {
+        "auto_generator.md": [
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator.__init__",
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator._render",
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator._initialize_generate",
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator._generate_docs",
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator._generate_static",
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator.generate",
+        ]
+    },
+    "Tools": {
+        "toolbox.md": [
+            # "mkdocstrings_sourcelink.toolbox.Utilities",
+            "mkdocstrings_sourcelink.toolbox.Utilities.insert_in_file",
+            "mkdocstrings_sourcelink.toolbox.Utilities.element_to_mkdocstrings",
+            "mkdocstrings_sourcelink.toolbox.Utilities.make_source_link",
+            "mkdocstrings_sourcelink.toolbox.Utilities.make_title",
+            "mkdocstrings_sourcelink.toolbox.Utilities.ismethod",
+            "mkdocstrings_sourcelink.toolbox.Utilities.import_object",
+            "mkdocstrings_sourcelink.toolbox.Utilities.return_as_Path",
+        ],
+    },
+}
+markdown_files = {"HOME": {"index.md": ["../README.md"]}}
+root = Path(__file__).resolve().parents[1]
+MkDocGenerator(
+    root / "docs" / "src",
+    pages,
+    "https://github.com",
+    markdown_files=markdown_files,
+    underline_title=True,
+    source=":material-github::material-source-branch:",
+).generate

mkdocstrings_sourcelink/__init__.py

@@ -1 +1,2 @@
 """ [summary] [extended_summary] """
+from .auto_generator import MkDocGenerator

mkdocstrings_sourcelink/auto_generator.py

@@ -42,13 +42,14 @@ class MkDocGenerator(Utilities, BuilderMkDoc):
 
     def __init__(
         self,
-        dest_dir: str,
+        dest_dir: Union[str, Path],
         documentation: Dict[str, Dict[str, List[str]]] = {},
         project_url: Union[str, Dict[str, str]] = None,
         template_dir: str = None,
         examples_dir: str = None,
         markdown_files: Dict[str, Dict[str, List[str]]] = None,
         titles_size: str = "##",
+        underline_title: bool = False,
         source: str = "**source code**",
         icon: str = None,
     ) -> None:
@@ -57,7 +58,7 @@ def __init__(
         [extended_summary]
 
         Args:
-            dest_dir (str): [description]
+            dest_dir (Union[str, Path]): [description]
             documentation (Dict[str, Dict[str, List[str]]], optional): [description]. Defaults to {}.
             project_url (Union[str, Dict[str, str]], optional): [description]. Defaults to None.
             template_dir (str, optional): [description]. Defaults to None.
@@ -74,6 +75,7 @@ def __init__(
         self.examples_dir = Utilities.return_as_Path(examples_dir)
         self.markdown_files = markdown_files
         self.titles_size = titles_size
+        self.underline_title = underline_title
         self.source = source
         self.icon = icon
 
@@ -90,15 +92,10 @@ def _render(self, element: str) -> str:
         """
         if isinstance(element, str):
             object_ = Utilities.import_object(element)
-            if Utilities.ismethod(object_):
-                # we remove the modules when displaying the methods
-                signature_override = ".".join(element.split(".")[-2:])
-            else:
-                signature_override = element
+            signature = element
         else:
-            signature_override = None
+            signature = None
             object_ = element
-
         subblocks = []
         if self.project_url:
             subblocks.append(
@@ -107,9 +104,11 @@ def _render(self, element: str) -> str:
                 )
             )
 
-        subblocks.append(Utilities.make_title(object_, self.titles_size))
-        subblocks.append(Utilities.element_to_mkdocstrings(signature_override))
-        return "\n\n".join(subblocks) + "\n\n----\n\n"
+        subblocks.append(
+            Utilities.make_title(object_, self.titles_size, self.underline_title)
+        )
+        subblocks.append(Utilities.element_to_mkdocstrings(signature))
+        return "\n\n".join(subblocks) + "\n\n"
 
     def _initialize_generate(self) -> None:
         """_initialize_generate [summary]

mkdocstrings_sourcelink/toolbox.py

@@ -3,7 +3,7 @@
 import inspect
 from abc import ABC, abstractmethod
 from pathlib import Path
-from typing import Any, Optional, Union
+from typing import Any, Dict, Optional, Union
 
 
 class BuilderUtilities(ABC):
@@ -92,18 +92,21 @@ def element_to_mkdocstrings(element: str) -> str:
         Returns:
             str: [description]
         """
-        return f":::{element}\n"
+        return f"### :::{element}\n"
 
     def make_source_link(
-        cls: Any, project_url: str, icon: str = None, source: str = "**source code**"
+        cls: Any,
+        project_url: Union[str, Dict[str, str]],
+        icon: str = None,
+        source: str = "**source code**",
     ) -> str:
         """make_source_link [summary]
 
         [extended_summary]
 
         Args:
             cls (Any): [description]
-            project_url (str): [description]
+            project_url (Union[str, Dict[str, str]]): [description]
             icon (str, optional): [description]. Defaults to None.
             source (str, optional): [description]. Defaults to "**source code**".
 
@@ -134,7 +137,7 @@ def make_source_link(
             f"</span>"
         )
 
-    def make_title(cls: Any, titles_size: str) -> str:
+    def make_title(cls: Any, titles_size: str, underline_title: bool) -> str:
         """make_title [summary]
 
         [extended_summary]
@@ -146,9 +149,10 @@ def make_title(cls: Any, titles_size: str) -> str:
         Returns:
             str: [description]
         """
+        title_underline = "\n---\n" if underline_title else "\n"
         if isinstance(cls, property):
-            return f"{titles_size} {cls.fget.__name__}\n"
-        return f"{titles_size} {cls.__name__}\n"
+            return f"{titles_size} {cls.fget.__name__}{title_underline}"
+        return f"{titles_size} {cls.__name__}{title_underline}"
 
     def ismethod(function: Any) -> Union[Any, bool]:
         """ismethod [summary]

setup.py

@@ -19,7 +19,7 @@
     long_description_content_type="text/markdown",
     url="https://github.com/AI2Business/mkdocstrings-sourcelink",
     license="Apache License 2.0",
-    extras_require={"tests": ["pytest", "pytest-pep8"]},
+    extras_require={"tests": ["pytest", "pytest-cov"]},
     classifiers=[
         "Natural Language :: English",
         "Operating System :: OS Independent",