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

* Revert workaround as sync-label bug was fixed in labeler-v5.0.0

* Updated missing documentation for mdx support

* Fixes functions not rendered during markdown generation and no "find_module" AttributeError

Caused by modules not correctly loaded into namespace from commit due to Issue #57.
Modules now correctly loaded into namespace.
Fixes AttributeError("'FileFinder' object has no attribute 'find_module'") (#69)
Prioritized "find_spec" and falls back to "find_module" from loader if find_spec not available.
Some whitespace removal.

* Overhauled docstring render and added Github flavour admonition support

Modify argument regex
Fix Colon use in docstring in arguments blocks now formatted correctly.
Change argument detection to last colon in line.
Added support for "Reference" as a block header.
Convert quote block to admonition blocks
Added Github admonition quote block support.
Added start line anchor to regex
Changed "```" code snippet boundary detection from startswith to regex to prevent false positives.

Rework docstring markdown render. Solves issue #80
Improved whitespace and newline rendering.
Accepts more native markdown syntax without garbling render.
Solves Issue #82

Enumerate the docstring to detect end of docstring to appropriately close literal blocks, doctest and code blocks

Update literal blocks logic and format.
Syntax is same as reStructured text

* Render class __init__ method as constructor using class name

* Support including private modules with, aka files with "_" prefix.

Add private_modules arg

* Add table of contents feature to module file

* Fixed incorrect and unsafe src href link

* Added feature for user override of url line anchor notation (#74)

* Forced generated markdown file to be platform independent

* Crude workaround for AttributeError, no attribute "__create_fn__" (#72)

Observed in python 3.8, constructor for dataclasses had different function signature

* Added rendering support for enum, dataclass, and exception

* Updated API document example and bump version to 0.6.0

Author: ltan10

.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__