Documentation

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: Union[str, Path] = None,
    example_dir: Union[str, Path] = None,
    markdown_files: Dict[str, Dict[str, List[str]]] = None,
    titles_size: str = "#",
    underline_title: bool = False,
    source: str = "**source code**",
) -> None:
    """Generates the documentation via `MkDocGenerator` with the links to the source.

    Args:
        dest_dir (Union[str, Path]): Destination of the generated documentation.
        documentation (Dict[str, Dict[str, List[str]]], optional): A nested dictionary with the
             page title, the page filename, and the functions /classes / methods names of the
             page. The dictionary should look like:
             `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 (including branch and storage).
        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.
        example_dir (Union[str, Path], optional): Directory of example 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:
             `pages = {'page_title':{'filename.md': ['existing_file.md']}}`.
        titles_size (str, optional): Defines the initial title size for the headings, which are
             scaled down by the factor of one "#".
        underline_title (bool, optional): Underline titles of classes, functions, and methods.
        source (str, optional): Name of the source link.

    !!! info "About *documentation*"
        In terms of linking to the project_url, it has to be separated between *specific* and
         *general* linking. If functions or method has to be separately linked, then each
         module of the class `Documentation` has to be called individually like:
        ```python
            pages = {
                "Documentation": {
                    "auto_generator.md": [
                        "mkdocstrings_sourcelink.auto_generator.MkDocGenerator.__init__",
                        "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",
                    ]
                }
            }
        ```
        If functions or method has to be generally linked, then just call the class
         `Documentation` is enough. It will be only generated one single link to the start of
          the class.
          ```python
              pages = {
                  "Documentation": {
                      "auto_generator.md": [
                          "mkdocstrings_sourcelink.auto_generator.MkDocGenerator",
                  }
              }
          ```
        For more information, please check: **mkdocstrings**
        https://github.com/pawamoy/mkdocstrings

    !!! tip "About *source*"
        Instead of using a string for `source = "**source code**"`, icons can be used instead
         or as combination of string + icon(s) like.
        ```python
            source = ":material-github::material-source-branch: source-code"
        ```
        In case of using material-icons, please check https://pictogrammers.github.io/@mdi/font/5.4.55/
        and replace `mdl` by `material`.

    !!! warning "About *project_url*"
        Keep in mind, that the name of the branch like *master*, *main*, or *dev*, as well as,
         the name of the storage like *blob* for GitHub has to be included.
    """
    self.dest_dir = Path(dest_dir)
    self.documentation = documentation
    self.project_url = project_url
    self.template_dir = Utilities.return_as_Path(template_dir)
    self.example_dir = Utilities.return_as_Path(example_dir)
    self.markdown_files = markdown_files
    self.titles_size = titles_size
    self.underline_title = underline_title
    self.source = source

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 a string in the mkdocstrings format.

    Returns:
        str: Return of the initial string which looks like
             `mkdocstrings_sourcelink.auto_generator.MkDocGenerator.__init__` into a markdown
             conformed string.
    """
    object_ = Utilities.import_object(element)
    subblocks = []
    if self.project_url:
        subblocks.append(
            Utilities.make_source_link(object_, self.project_url, self.source)
        )

    subblocks.append(
        Utilities.make_title(object_, self.titles_size, self.underline_title)
    )
    subblocks.append(Utilities.element_to_mkdocstrings(element, self.titles_size))
    return "\n\n".join(subblocks) + "\n\n"

def initialize_generate(self) -> None:
    """Initialization of the auto documentation generatorion.

    1. Firs removing a possible existing target directory (`dest_dir`).
    2. Copy templates from the template directory the target directory(`dest_dir`).
    3. Copy example from the example directory the target directory (`dest_dir`).
    """
    if self.dest_dir.exists():
        print(f"Cleaning up existing sources directory '{self.dest_dir}'.")
        shutil.rmtree(self.dest_dir)

    if self.template_dir:
        print(
            f"...copying existing sources directory '{self.template_dir}' to '{self.dest_dir}'."
        )
        shutil.copytree(self.template_dir, self.dest_dir)

    if self.example_dir:
        print(
            f"...copying existing sources directory '{self.example_dir}' to '{self.dest_dir}'."
        )
        shutil.copytree(self.example_dir, self.dest_dir)

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_to_markdown(element) for element in elements
            )
        Utilities.insert_in_file(markdown_text, self.dest_dir.joinpath(file_path))

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():
            markdown_text = ""
            for file_path, elements in markdown_files.items():
                markdown_text += "".join(
                    Path(element).read_text() for element in elements
                )
            Utilities.insert_in_file(
                markdown_text, self.dest_dir.joinpath(file_path)
            )