Finished docs

Documentation is finished.
Missing test and CI/CD

.pre-commit-config.yaml

@@ -11,6 +11,14 @@ repos:
       rev: ''
       hooks:
         - id: check-added-large-files
+    - repo: https://github.com/asottile/setup-cfg-fmt
+      rev: v1.16.0
+      hooks:
+        - id: setup-cfg-fmt
+    - repo: https://github.com/pycqa/pydocstyle
+      rev: 5.1.1  # pick a git hash / tag to point to
+      hooks:
+      - id: pydocstyle
     - repo: local
       hooks:
         - id: pylint
@@ -19,9 +27,4 @@ repos:
           language: system
           always_run: true
           pass_filenames: false
-        - id: pydocstyle
-          name: pydocstyle
-          entry: pydocstyle mkdocstrings_sourcelink
-          language: python
-          types: [python]
 

docs/generate_docs.py

@@ -1,3 +1,4 @@
+"""Generate Docstring via MkDocGenerator of mkdocstrings-sourcelink."""
 from pathlib import Path
 
 from mkdocstrings_sourcelink import MkDocGenerator
@@ -6,32 +7,37 @@
     "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.render_to_markdown",
+            "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",
         ],
     },
+    "API": {
+        "api.md": [
+            "mkdocstrings_sourcelink.auto_generator.MkDocGenerator",
+            "mkdocstrings_sourcelink.toolbox.Utilities",
+        ],
+    },
 }
 markdown_files = {"HOME": {"index.md": ["../README.md"]}}
 root = Path(__file__).resolve().parents[1]
 MkDocGenerator(
     root / "docs" / "src",
     pages,
     "https://github.com/AI2Business/mkdocstrings-sourcelink",
+    root / "docs" / "tmp",
     markdown_files=markdown_files,
     underline_title=True,
     source=":material-github::material-source-branch:",

docs/mkdocs.yml

@@ -130,6 +130,8 @@ plugins:
 
 nav:
   - Home: index.md
-  - Documentation: auto_generator.md
-  - Tools: toolbox.md
-  #- Tools: toolbox.md
+  - Documentation:
+    - About: about.md
+    - Automatic Doc Generator: auto_generator.md
+    - Tools: toolbox.md
+  - API: api.md

docs/theme/main.html

@@ -0,0 +1,22 @@
+{% extends "base.html" %}
+
+{% block libs %}
+{{ super() }}
+{% include "partials/libs.html" ignore missing %}
+{% endblock %}
+
+{% block announce %}{% include "announce.html" ignore missing %}{% endblock %}
+
+{% block content %}
+  {{ super() }}
+  <footer class="insider">
+    <hr>
+    <a href="https://github.com/ai2business/mkdocstrings" title="Become an insider">
+      <span class="twemoji heart-throb-hover">
+        {% set icon = "octicons/heart-fill-16" %}
+        {% include ".icons/" ~ icon ~ ".svg" %}
+      </span>
+    </a>
+    <hr>
+  </footer>
+{% endblock %}

mkdocstrings_sourcelink/auto_generator.py

@@ -8,44 +8,50 @@
 
 
 class BuilderMkDoc(ABC):
-    """BuilderMkDoc is the Metaclass of MkDocGenerator.
+    """BuilderMkDoc is the Metaclass of `MkDocGenerator`.
 
     Args:
         ABC (class): Helper class that provides a standard way to create an ABC using
              inheritance.
     """
 
     @abstractmethod
-    def _render(self, element: str) -> str:
-        """Abstract the internal method of `_render`."""
+    def render_to_markdown(self, element: str) -> str:
+        """Abstract the internal method of `render_to_markdown`."""
 
     @abstractmethod
-    def _initialize_generate(self) -> None:
-        """Abstract the internal method of `_initialize_generate`."""
+    def initialize_generate(self) -> None:
+        """Abstract the internal method of `initialize_generate`."""
 
     @abstractmethod
-    def _generate_docs(self) -> None:
-        """Abstract the internal method of `_generate_docs`."""
+    def generate_docs(self) -> None:
+        """Abstract the internal method of `generate_docs`."""
 
     @abstractmethod
-    def _generate_static(self) -> None:
-        """Abstract the internal method of `_generate_static`."""
+    def generate_static(self) -> None:
+        """Abstract the internal method of `generate_static`."""
 
     @abstractproperty
     def generate(self) -> None:
         """Abstract the property of `generate`."""
 
 
 class MkDocGenerator(Utilities, BuilderMkDoc):
-    """Generates the documentation withthe links to the source."""
+    """The `MkDocGenerator` generates the documentation with the links to the source code.
+
+    Args:
+        Utilities (class): [description]
+        BuilderMkDoc (class): Builder class of the abstract methods and property of
+             `MkDocGenerator`.
+    """
 
     def __init__(
         self,
         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,
+        template_dir: Union[str, Path] = None,
+        examples_dir: Union[str, Path] = None,
         markdown_files: Dict[str, Dict[str, List[str]]] = None,
         titles_size: str = "#",
         underline_title: bool = False,
@@ -61,11 +67,11 @@ def __init__(
                  `pages = {'page_title':{'filename.md': ['package.module.function']}}`.
             project_url (Union[str, Dict[str, str]], optional): The URL, where the project is
                  hosted and where it should be linked to.
-            template_dir (str, optional): Directory of template files. If template has
+            template_dir (Union[str, Path], optional): Directory of template files. If template has
                  to be automatically filled out, then the keyword **{{autogenerated}}** has to be
                  used.
-            examples_dir (str, optional): Directory of examples files, especially suitable for
-                `Jupyter-Notebooks`.
+            examples_dir (Union[str, Path], optional): Directory of examples files, especially
+                 suitable for `Jupyter-Notebooks`.
             markdown_files (Dict[str, Dict[str, List[str]]], optional): A nested dictionary with
                  the page title, the page filename, and the link to already existing markdown files
                  like **README.md** or **LICENSE**. The dictionary should look like:
@@ -84,10 +90,10 @@ def __init__(
                     "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.render_to_markdown",
+                            "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",
                         ]
                     }
@@ -126,12 +132,12 @@ def __init__(
         self.underline_title = underline_title
         self.source = source
 
-    def _render(self, element: str) -> str:
+    def render_to_markdown(self, element: str) -> str:
         """Rendering the element path to mkdocstrings.
 
         Args:
             element (str): String of they python class, function, or method, which has to be
-                 converted to string for markdown.
+                 converted to a string in the mkdocstrings format.
 
         Returns:
             str: Return of the initial string which looks like
@@ -156,7 +162,7 @@ def _render(self, element: str) -> str:
         subblocks.append(Utilities.element_to_mkdocstrings(signature, self.titles_size))
         return "\n\n".join(subblocks) + "\n\n"
 
-    def _initialize_generate(self) -> None:
+    def initialize_generate(self) -> None:
         """Initialization of the auto documentation generatorion.
 
         1. Firs removing a possible existing target directory (`dest_dir`).
@@ -179,15 +185,17 @@ def _initialize_generate(self) -> None:
             )
             shutil.copytree(self.example_dir, self.dest_dir)
 
-    def _generate_docs(self) -> None:
+    def generate_docs(self) -> None:
         """Generated *dynamic* documentation based on calling the elements via dictionary."""
         for title, documentation in self.documentation.items():
             markdown_text = f"{self.titles_size} {title}\n\n---\n\n"
             for file_path, elements in documentation.items():
-                markdown_text += "".join(self._render(element) for element in elements)
+                markdown_text += "".join(
+                    self.render_to_markdown(element) for element in elements
+                )
             Utilities.insert_in_file(markdown_text, self.dest_dir.joinpath(file_path))
 
-    def _generate_static(self) -> None:
+    def generate_static(self) -> None:
         """Generate *static* documentation based on existing markdown files."""
         if self.markdown_files:
             for _, markdown_files in self.markdown_files.items():
@@ -215,10 +223,10 @@ def generate(self) -> None:
                 "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.render_to_markdown",
+                        "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",
                     ]
                 },
@@ -228,7 +236,6 @@ def generate(self) -> None:
                         "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",
                     ],
@@ -249,6 +256,6 @@ def generate(self) -> None:
             >>> ...
             ```
         """
-        self._initialize_generate()
-        self._generate_docs()
-        self._generate_static()
+        self.initialize_generate()
+        self.generate_docs()
+        self.generate_static()

mkdocstrings_sourcelink/test/__init__.py

@@ -0,0 +1 @@
+"""Test module of mkdocstrings-sourcelink."""