diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index e47dd4f..d6ee4b9 100644 --- a/.pre-commit-config.yaml +++ b/.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 diff --git a/doc-requirements.txt b/doc-requirements.txt new file mode 100644 index 0000000..02e4da7 --- /dev/null +++ b/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 \ No newline at end of file diff --git a/docs/generate_docs.py b/docs/generate_docs.py new file mode 100644 index 0000000..4365759 --- /dev/null +++ b/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 diff --git a/mkdocstrings-sourcelink/__init__.py b/mkdocstrings-sourcelink/__init__.py deleted file mode 100644 index e69de29..0000000 diff --git a/mkdocstrings_sourcelink/__init__.py b/mkdocstrings_sourcelink/__init__.py index a58b021..4b73273 100644 --- a/mkdocstrings_sourcelink/__init__.py +++ b/mkdocstrings_sourcelink/__init__.py @@ -1 +1,2 @@ """ [summary] [extended_summary] """ +from .auto_generator import MkDocGenerator diff --git a/mkdocstrings_sourcelink/auto_generator.py b/mkdocstrings_sourcelink/auto_generator.py index 89cd38c..1d23b11 100644 --- a/mkdocstrings_sourcelink/auto_generator.py +++ b/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] diff --git a/mkdocstrings_sourcelink/toolbox.py b/mkdocstrings_sourcelink/toolbox.py index a5b1027..b8514e1 100644 --- a/mkdocstrings_sourcelink/toolbox.py +++ b/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,10 +92,13 @@ 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] @@ -103,7 +106,7 @@ def make_source_link( 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"" ) - 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] diff --git a/setup.py b/setup.py index ef0477a..4e42075 100644 --- a/setup.py +++ b/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",