Docstring markdown render overhaul (preserves markdown syntax), new features and bugfixes including no find_module AttributeError fix

.github/workflows/pr-labeler.yml

@@ -12,7 +12,7 @@ jobs:
           repo-token: "${{ secrets.GITHUB_TOKEN }}"
           configuration-path: .github/pr-labeler-file-path.yml
           # workaround for problem: https://github.com/wesnoth/wesnoth/commit/958c82d0867568057caaf58356502ec8c87d8366
-          sync-labels: ""
+          sync-labels: false
       - uses: TimonVS/pr-labeler-action@v3
         with:
           configuration-path: .github/pr-labeler-branch-name.yml

README.md

@@ -171,11 +171,15 @@ lazydocs [OPTIONS] PATHS...
 
 * `--output-path TEXT`: The output path for the creation of the markdown files. Set this to `stdout` to print all markdown to stdout.  [default: ./docs/]
 * `--src-base-url TEXT`: The base repo link used as prefix for all source links. Should also include the branch name.
+* `--url-line-prefix TEXT`: Line prefix for git repository line url anchors #{prefix}line. If None provided, defaults to Github style notation.
 * `--overview-file TEXT`: Filename of overview file. If not provided, no API overview file will be generated.
 * `--remove-package-prefix / --no-remove-package-prefix`: If `True`, the package prefix will be removed from all functions and methods.  [default: True]
 * `--ignored-modules TEXT`: A list of modules that should be ignored.  [default: ]
 * `--watermark / --no-watermark`: If `True`, add a watermark with a timestamp to bottom of the markdown files.  [default: True]
 * `--validate / --no-validate`: If `True`, validate the docstrings via pydocstyle. Requires pydocstyle to be installed.  [default: False]
+* `--output-format TEXT`: The output format for the creation of the markdown files. This may be 'md' or 'mdx'. Defaults to md.
+* `--private-modules / --no-private-modules`: If `True`, includes modules with "_" prefix. [default: False]
+* `--toc / --no-toc`: If `True`, includes table of contents in generated module markdown files. [default: False]
 * `--install-completion`: Install completion for the current shell.
 * `--show-completion`: Show completion for the current shell, to copy it or customize the installation.
 * `--help`: Show this message and exit.

docs/lazydocs.generation.md

@@ -1,14 +1,28 @@
 <!-- markdownlint-disable -->
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L0"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 # <kbd>module</kbd> `lazydocs.generation`
-Main module for markdown generation. 
+Main module for markdown generation.
+
+
+## Table of Contents
+- [`MarkdownGenerator`](./lazydocs.generation.md#class-markdowngenerator)
+	- [`__init__`](./lazydocs.generation.md#constructor-__init__)
+	- [`class2md`](./lazydocs.generation.md#method-class2md)
+	- [`func2md`](./lazydocs.generation.md#method-func2md)
+	- [`import2md`](./lazydocs.generation.md#method-import2md)
+	- [`module2md`](./lazydocs.generation.md#method-module2md)
+	- [`overview2md`](./lazydocs.generation.md#method-overview2md)
+	- [`toc2md`](./lazydocs.generation.md#method-toc2md)
+- [`generate_docs`](./lazydocs.generation.md#function-generate_docs)
+- [`to_md_file`](./lazydocs.generation.md#function-to_md_file)
+
 
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L197"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L223"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ## <kbd>function</kbd> `to_md_file`
 
@@ -18,26 +32,28 @@ to_md_file(
     filename: str,
     out_path: str = '.',
     watermark: bool = True,
-    disable_markdownlint: bool = True
+    disable_markdownlint: bool = True,
+    is_mdx: bool = False
 ) → None
 ```
 
-Creates an API docs file from a provided text. 
-
+Creates an API docs file from a provided text.
 
 
 **Args:**
-
- - <b>`markdown_str`</b> (str):  Markdown string with line breaks to write to file. 
- - <b>`filename`</b> (str):  Filename without the .md 
- - <b>`watermark`</b> (bool):  If `True`, add a watermark with a timestamp to bottom of the markdown files. 
- - <b>`disable_markdownlint`</b> (bool):  If `True`, an inline tag is added to disable markdownlint for this file. 
- - <b>`out_path`</b> (str):  The output directory 
+
+- <b>`markdown_str`</b> (str): Markdown string with line breaks to write to file.
+- <b>`filename`</b> (str): Filename without the .md
+- <b>`out_path`</b> (str): The output directory.
+- <b>`watermark`</b> (bool): If `True`, add a watermark with a timestamp to bottom of the markdown files.
+- <b>`disable_markdownlint`</b> (bool): If `True`, an inline tag is added to disable markdownlint for this file.
+- <b>`is_mdx`</b> (bool, optional): JSX support. Default to False.
+
 
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L889"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L1158"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ## <kbd>function</kbd> `generate_docs`
 
@@ -49,173 +65,225 @@ generate_docs(
     src_base_url: Optional[str] = None,
     remove_package_prefix: bool = False,
     ignored_modules: Optional[List[str]] = None,
+    output_format: Optional[str] = None,
     overview_file: Optional[str] = None,
     watermark: bool = True,
-    validate: bool = False
+    validate: bool = False,
+    private_modules: bool = False,
+    include_toc: bool = False,
+    url_line_prefix: Optional[str] = None
 ) → None
 ```
 
-Generates markdown documentation for provided paths based on Google-style docstrings. 
-
+Generates markdown documentation for provided paths based on Google-style docstrings.
 
 
 **Args:**
-
- - <b>`paths`</b>:  Selected paths or import name for markdown generation. 
- - <b>`output_path`</b>:  The output path for the creation of the markdown files. Set this to `stdout` to print all markdown to stdout. 
- - <b>`src_root_path`</b>:  The root folder name containing all the sources. Fallback to git repo root. 
- - <b>`src_base_url`</b>:  The base url of the github link. Should include branch name. All source links are generated with this prefix. 
- - <b>`remove_package_prefix`</b>:  If `True`, the package prefix will be removed from all functions and methods. 
- - <b>`ignored_modules`</b>:  A list of modules that should be ignored. 
- - <b>`overview_file`</b>:  Filename of overview file. If not provided, no overview file will be generated. 
- - <b>`watermark`</b>:  If `True`, add a watermark with a timestamp to bottom of the markdown files. 
- - <b>`validate`</b>:  If `True`, validate the docstrings via pydocstyle. Requires pydocstyle to be installed. 
+
+- <b>`paths`</b>: Selected paths or import name for markdown generation.
+- <b>`output_path`</b>: The output path for the creation of the markdown files. Set this to `stdout` to print all markdown to stdout.
+- <b>`src_root_path`</b>: The root folder name containing all the sources. Fallback to git repo root.
+- <b>`src_base_url`</b>: The base url of the github link. Should include branch name. All source links are generated with this prefix.
+- <b>`remove_package_prefix`</b>: If `True`, the package prefix will be removed from all functions and methods.
+- <b>`ignored_modules`</b>: A list of modules that should be ignored.
+- <b>`output_format`</b>: Markdown file extension and format.
+- <b>`overview_file`</b>: Filename of overview file. If not provided, no overview file will be generated.
+- <b>`watermark`</b>: If `True`, add a watermark with a timestamp to bottom of the markdown files.
+- <b>`validate`</b>: If `True`, validate the docstrings via pydocstyle. Requires pydocstyle to be installed.
+- <b>`private_modules`</b>: If `True`, includes modules with `_` prefix.
+- <b>`url_line_prefix: Line prefix for git repository line url anchors. Default`</b>: None - github "L".
+
 
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L454"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L627"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ## <kbd>class</kbd> `MarkdownGenerator`
-Markdown generator class. 
+Markdown generator class.
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L457"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
-### <kbd>method</kbd> `__init__`
+<a href="../src/lazydocs/generation.py#L630"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+
+### <kbd>constructor</kbd> `__init__`
 
 ```python
-__init__(
+MarkdownGenerator(
     src_root_path: Optional[str] = None,
     src_base_url: Optional[str] = None,
-    remove_package_prefix: bool = False
+    remove_package_prefix: bool = False,
+    url_line_prefix: Optional[str] = None
 )
 ```
 
-Initializes the markdown API generator. 
-
+Initializes the markdown API generator.
 
 
 **Args:**
-
- - <b>`src_root_path`</b>:  The root folder name containing all the sources. 
- - <b>`src_base_url`</b>:  The base github link. Should include branch name.  All source links are generated with this prefix. 
- - <b>`remove_package_prefix`</b>:  If `True`, the package prefix will be removed from all functions and methods. 
+
+- <b>`src_root_path`</b>: The root folder name containing all the sources.
+- <b>`src_base_url`</b>: The base github link. Should include branch name.
+    All source links are generated with this prefix.
+- <b>`remove_package_prefix`</b>: If `True`, the package prefix will be removed from all functions and methods.
+- <b>`url_line_prefix: Line prefix for git repository line url anchors. Default`</b>: None - github "L".
+
 
 
 
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L609"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L795"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ### <kbd>method</kbd> `class2md`
 
 ```python
-class2md(cls: Any, depth: int = 2) → str
+class2md(cls: Any, depth: int = 2, is_mdx: bool = False) → str
 ```
 
-Takes a class and creates markdown text to document its methods and variables. 
-
+Takes a class and creates markdown text to document its methods and variables.
 
 
 **Args:**
-
- - <b>`cls`</b> (class):  Selected class for markdown generation. 
- - <b>`depth`</b> (int, optional):  Number of # to append to function name. Defaults to 2. 
 
+- <b>`cls`</b> (class): Selected class for markdown generation.
+- <b>`depth`</b> (int, optional): Number of # to append to function name. Defaults to 2.
+- <b>`is_mdx`</b> (bool, optional): JSX support. Default to False.
 
 
 **Returns:**
-
- - <b>`str`</b>:  Markdown documentation for selected class. 
+
+- <b>`str`</b>: Markdown documentation for selected class.
+
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L524"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L706"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ### <kbd>method</kbd> `func2md`
 
 ```python
-func2md(func: Callable, clsname: str = '', depth: int = 3) → str
+func2md(
+    func: Callable,
+    clsname: str = '',
+    depth: int = 3,
+    is_mdx: bool = False
+) → str
 ```
 
-Takes a function (or method) and generates markdown docs. 
-
+Takes a function (or method) and generates markdown docs.
 
 
 **Args:**
-
- - <b>`func`</b> (Callable):  Selected function (or method) for markdown generation. 
- - <b>`clsname`</b> (str, optional):  Class name to prepend to funcname. Defaults to "". 
- - <b>`depth`</b> (int, optional):  Number of # to append to class name. Defaults to 3. 
 
+- <b>`func`</b> (Callable): Selected function (or method) for markdown generation.
+- <b>`clsname`</b> (str, optional): Class name to prepend to funcname. Defaults to "".
+- <b>`depth`</b> (int, optional): Number of # to append to class name. Defaults to 3.
+- <b>`is_mdx`</b> (bool, optional): JSX support. Default to False.
 
 
 **Returns:**
-
- - <b>`str`</b>:  Markdown documentation for selected function. 
+
+- <b>`str`</b>: Markdown documentation for selected function.
+
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L815"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L1046"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ### <kbd>method</kbd> `import2md`
 
 ```python
-import2md(obj: Any, depth: int = 1) → str
+import2md(
+    obj: Any,
+    depth: int = 1,
+    is_mdx: bool = False,
+    include_toc: bool = False
+) → str
 ```
 
-Generates markdown documentation for a selected object/import. 
-
+Generates markdown documentation for a selected object/import.
 
 
 **Args:**
-
- - <b>`obj`</b> (Any):  Selcted object for markdown docs generation. 
- - <b>`depth`</b> (int, optional):  Number of # to append before heading. Defaults to 1. 
 
+- <b>`obj`</b> (Any): Selcted object for markdown docs generation.
+- <b>`depth`</b> (int, optional): Number of # to append before heading. Defaults to 1.
+- <b>`is_mdx`</b> (bool, optional): JSX support. Default to False.
+- <b>`include_toc`</b> (bool, Optional): Include table of contents for module file. Defaults to False.
 
 
 **Returns:**
-
- - <b>`str`</b>:  Markdown documentation of selected object. 
+
+- <b>`str`</b>: Markdown documentation of selected object.
+
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L720"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L943"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ### <kbd>method</kbd> `module2md`
 
 ```python
-module2md(module: module, depth: int = 1) → str
+module2md(
+    module: module,
+    depth: int = 1,
+    is_mdx: bool = False,
+    include_toc: bool = False
+) → str
 ```
 
-Takes an imported module object and create a Markdown string containing functions and classes. 
-
+Takes an imported module object and create a Markdown string containing functions and classes.
 
 
 **Args:**
-
- - <b>`module`</b> (types.ModuleType):  Selected module for markdown generation. 
- - <b>`depth`</b> (int, optional):  Number of # to append before module heading. Defaults to 1. 
 
+- <b>`module`</b> (types.ModuleType): Selected module for markdown generation.
+- <b>`depth`</b> (int, optional): Number of # to append before module heading. Defaults to 1.
+- <b>`is_mdx`</b> (bool, optional): JSX support. Default to False.
+- <b>`include_toc`</b> (bool, optional): Include table of contents in module file. Defaults to False.
 
 
 **Returns:**
-
- - <b>`str`</b>:  Markdown documentation for selected module. 
+
+- <b>`str`</b>: Markdown documentation for selected module.
+
 
 ---
 
-<a href="https://github.com/ml-tooling/lazydocs/blob/main/src/lazydocs/generation.py#L835"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+<a href="../src/lazydocs/generation.py#L1068"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
 
 ### <kbd>method</kbd> `overview2md`
 
 ```python
-overview2md() → str
+overview2md(is_mdx: bool = False) → str
+```
+
+Generates a documentation overview file based on the generated docs.
+
+
+**Args:**
+
+- <b>`is_mdx`</b> (bool, optional): JSX support. Default to False.
+
+
+**Returns:**
+
+- <b>`str`</b>: Markdown documentation of overview file.
+
+
+---
+
+<a href="../src/lazydocs/generation.py#L1137"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square" /></a>
+
+### <kbd>method</kbd> `toc2md`
+
+```python
+toc2md(module: module = None, is_mdx: bool = False) → str
 ```
 
-Generates a documentation overview file based on the generated docs. 
+Generates table of contents for imported object.
+
 
 
 

src/lazydocs/_about.py

@@ -1,5 +1,5 @@
 """Information about this library. This file will automatically changed."""
 
-__version__ = "0.5.1"
+__version__ = "0.6.0"
 # __author__
 # __email__