ml-tooling / lazydocs Goto Github PK

I have added certain external modules to the --ignored-modules flag, however lazydocs still fails to generate docs for my modules which leverage these external modules, giving a ModuleNotFoundError.
My modules depend on many other libraries which are enterprise-specific and cannot be pip installed easily, especially when using a virtual machine with GitHub Actions to run my MkDocs logic. I do not want to have to import all of these just for lazydocs.
I am only trying to generate some very basic documentation for my own library, I am fine with not providing further information on the external libraries we are leveraging.
Can I have an option of simply bypassing these ModuleNotFoundErrors, where the markdown is still generated just without information for the uninstalled external modules?

Describe the bug:

The generated .md files contain links to the source code, that include an <img> tag.
When taking those markdown files and process them by html generators (which we do in our release pipelines, towards netlify), that html is considered as 'not compliant' by some generators.

Expected behaviour:

The image tag should be closed , like this : <img ... />, instead of this <img ...>

Steps to reproduce the issue:

1. Generate docs, using lazydocs.
2. Navigate to the generated .md file
3. Verify the <img> tag is not closed

Possible Fix:

The file lazydocs.generation.md should be adapted to close the img tags.

Describe the bug:

When a fenced code block includes a doctest test (specifically >>> prompts), the generated markdown is incorrect.

Expected behaviour:

Fenced code blocks containing >>> should render just like any other fenced code block.

For example, this docstring:

"""Compute the sum of 2 numbers.

Examples:

```plain
>>> add(1, 2)
3
>>> add(2, 2)
4
```
"""

should generate the following markdown:

Compute the sum of two numbers. 



**Examples:**
 

```plain
>>> add(1, 2)
3
>>> add(2, 2)
4
``` 

Unfortunately, it produces the following instead:

Compute the sum of two numbers. 



**Examples:**
 

```plain
``` add(1, 2)``` 3 ``` add(2, 2)```
4
``` 

And the resulting HTML does not render as expected.

Steps to reproduce the issue:

See example docstring above.

Technical details:

• Host Machine OS (Windows/Linux/Mac): Mac
• Browser (Chrome/Firefox/Safari): Any

Possible Fix:

I have not looked at the lazydocs code, so I don't know, but happy to dig in, if it would help.

Additional context:

None

Describe the bug:

When generating documentation the source badge creates non-compliant URLs. Specifically, when combining value provided by -src-base-url with the path, it seems to use the OS specific path separator. This results in URLs that look like:

https://src-base-url/path/to/repo\file.py

Expected behaviour:

I would expect this to function correctly on any operating system. Rather than the incorrect URL above, the source badge should use the correct path separator:

https://src-base-url/path/to/repo/file.py

Steps to reproduce the issue:

Run lazydocs on Windows with virtually any configuration. I run it specifying an output path and base url for the source.

Technical details:

• Host Machine OS (Windows/Linux/Mac): Windows
• Browser (Chrome/Firefox/Safari): Firefox

Possible Fix:

In generation.py rather than os.path.join I would suggest using urljoin from urllib. Example:

from urllib.parse import urljoin

# ... generation.py contents...

        if append_base and self.src_base_url:
            relative_path = urljoin(self.src_base_url, relative_path)

# ... everything else...

Additional context:
https://docs.python.org/3/library/urllib.parse.html#urllib.parse.urljoin

Disclaimer

I am rather new to lazydocs and would also not consider myself as a Python guru. So, I may miss some obvious things, so please bear with me.

Feature description:

I have a Python module with the following structure. And I would like to exclude the files of the 'mother-modules'. (in this case the image module):

So, above you can see I have directories to split the different modules and group them by functionality. The problem is that there is also a file generated with the name 'ml.images.md'. And that file does not contain any documentation, other than its title.
So, what I want is a way to skip the generation of the ml.images.md file, but still generate the sub module documents, such as ml.images.explorer.md, ml.images.conversion.md, ml.images.io.md.

The parameter when I pass the following argument value ignored_modules=['ml.evaluation'] to the generate_docs() method, it skips the entire directory.

Repro

I am running the following code to generate the .md files, based on the files in my module directory. And I want to exclude the generation of the ml.evaluation.md file.

from lazydocs import generate_docs
import glob, os, os.path

# Remove all files
sdk_docs_dir = 'docs/preview/sdk'
filelist = glob.glob(os.path.join(sdk_docs_dir, "*.md"))
for f in filelist:
    os.remove(f)
generate_docs(['arcus'], output_path=sdk_docs_dir, overview_file="index.md", remove_package_prefix=True)

Problem and motivation:

As there is no 'real' module images, but only a folder in the module hierarchy, I would like to prevent the generation of the empty mark down file. Now it adds empty files, which don't look great.

Describe the bug:

Running act -b -j build fails as follows:

$ act -b -j build
INFO[0000] Using docker host 'unix:///var/run/docker.sock', and daemon socket 'unix:///var/run/docker.sock' 
[build-pipeline/build] 🚀  Start image=catthehacker/ubuntu:act-latest
[build-pipeline/build]   🐳  docker pull image=catthehacker/ubuntu:act-latest platform= username= forcePull=true
[build-pipeline/build]   🐳  docker create image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[build-pipeline/build]   🐳  docker run image=catthehacker/ubuntu:act-latest platform= entrypoint=["tail" "-f" "/dev/null"] cmd=[] network="host"
[build-pipeline/build] ⭐ Run Main set-input-build-args
[build-pipeline/build]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/0] user= workdir=
[build-pipeline/build]   ✅  Success - Main set-input-build-args
[build-pipeline/build]   ⚙  ::set-env:: BUILD_ARGS=
[build-pipeline/build] ⭐ Run Main set-input-working-directory
[build-pipeline/build]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/1] user= workdir=
[build-pipeline/build]   ✅  Success - Main set-input-working-directory
[build-pipeline/build]   ⚙  ::set-env:: WORKING_DIRECTORY=
[build-pipeline/build] ⭐ Run Main set-host-ip
[build-pipeline/build]   🐳  docker exec cmd=[bash --noprofile --norc -e -o pipefail /var/run/act/workflow/2] user= workdir=
[build-pipeline/build]   ✅  Success - Main set-host-ip
[build-pipeline/build]   ⚙  ::set-env:: _HOST_IP=192.168.65.3
[build-pipeline/build] ⭐ Run Main actions/checkout@v2
[build-pipeline/build]   ✅  Success - Main actions/checkout@v2
[build-pipeline/build] ⭐ Run Main run-build-scripts
[build-pipeline/build]   🐳  docker build -t act-github-actions-build-environment-dockeraction:latest /Users/charlie/src/chuckwondo/lazydocs/.github/actions/build-environment/
[build-pipeline/build]   🐳  docker pull image=act-github-actions-build-environment-dockeraction:latest platform= username= forcePull=false
[build-pipeline/build]   🐳  docker create image=act-github-actions-build-environment-dockeraction:latest platform= entrypoint=[] cmd=[] network="container:act-build-pipeline-build-204bc7dcf518e94b319efa5333933555e09951350edb67061750c9b53102ca14"
[build-pipeline/build]   🐳  docker run image=act-github-actions-build-environment-dockeraction:latest platform= entrypoint=[] cmd=[] network="container:act-build-pipeline-build-204bc7dcf518e94b319efa5333933555e09951350edb67061750c9b53102ca14"
| json: cannot unmarshal array into Go value of type types.ContainerJSON
| jq: error (at <stdin>:1): Cannot iterate over null (null)
| json: cannot unmarshal array into Go value of type types.ContainerJSON
| jq: error (at <stdin>:1): Cannot iterate over null (null)
[build-pipeline/build]   ❌  Failure - Main run-build-scripts
[build-pipeline/build] exit with `FAILURE`: 5
[build-pipeline/build] 🏁  Job failed
Error: Job 'build' failed

Expected behaviour:

Build should succeed.

Steps to reproduce the issue:

Run act -b -j build

Technical details:

• Host Machine OS (Windows/Linux/Mac): Mac
• Browser (Chrome/Firefox/Safari): N/A

Possible Fix:

Additional context:

$ act --version
act version 0.2.64

Would like to use the --ignored-modules feature via the CLI but all uses I can think of result in what is presumably an AttributeError: 'tuple' object has no attribute 'append' being raised.

Am trying:
lazydocs --overview-file="README.md" --ignored-modules __verison__ <my module>docs
lazydocs --overview-file="README.md" --ignored-modules="__verison__" <my module>docs
lazydocs --overview-file="README.md" --ignored-modules __verison__ <my module>docs

How should the arguments to --overview-file be formatted?

On Windows 10, Python 3.6.8

Describe the bug:

On a very simple type annotated function, I get:

Writing api.md.
Failed to generate docs for module api: UnicodeEncodeError('charmap', '<!-- markdownlint-disable -->\r\n\r\n# <kbd>module</kbd> `api`\r\n\r\n\r\n\r\n\r\n\r\n---\r\n\r\n## <kbd>function</kbd> `to_string`\r\n\r\n```python\r\nto_string(value: int) → str\r\n```\r\n\r\nSimple function. \r\n\r\n\r\n\r\n**Args:**\r\n \r\n - <b>`value`</b>:  integer value \r\n\r\n\r\n\r\n**Returns:**\r\n same value as string \r\n\r\n\r\n', 148, 149, 'character maps to <undefined>')

Expected behaviour:

Should generate markdown file.

Steps to reproduce the issue:

1. On windows make sure your local default encoding is not utf8 (windows console defaults to cp1252)
2. Run lazydocs generation on any code that has type annotations.

Technical details:

• Host Machine OS (Windows/Linux/Mac): Windows 10
• Browser (Chrome/Firefox/Safari): Firefox

Possible Fix:

There's a hacky solution to make sure python is defaulting to 'utf8' when opening files:

if os.name == "nt":
    import _locale
    _locale._gdl_bak = _locale._getdefaultlocale
    _locale._getdefaultlocale = (lambda *args: (_locale._gdl_bak()[0], 'utf8'))

However, I'd advise against it as it may not be exactly future proof. Instead, it is better to be explicit when opening a file:

    with open(os.path.join(out_path, md_file), "w", encoding="utf-8") as f:

The line in question is here:

Describe the bug:

Generating docs fails with no real indication of what the issue is.

Expected behaviour:

A reference to the specific bad method.

Steps to reproduce the issue:

The failure was on this repo: EternityForest/iot_devices@8a63394

But I suspect the actual error itself is on my end and the issue is just with a lack of clarity in the error message.

Hi,

There is a command line argument type conversion issue (related to Typer).

When "ignored_modules" is set multiple times, the variable is not converted into a list but into a tuple.

$ lazydocs ./app --ignored-modules "main" --ignored-modules "tests" --overview-file README.md
Source path:... /Users/razy69/.pyenv/versions/3.9.6/envs/test39/lib/python3.9/site-packages/lazydocs/generation.py
Starting var:.. paths = ('./app',)
Starting var:.. output_path = './docs/'
Starting var:.. src_root_path = None
Starting var:.. src_base_url = None
Starting var:.. remove_package_prefix = True
Starting var:.. ignored_modules = ('main', 'tests')
Starting var:.. overview_file = 'README.md'
Starting var:.. watermark = True
Starting var:.. validate = False
...
11:29:20.267269 line       963             for loader, module_name, _ in pkgutil.walk_packages([path]):
Modified var:.. loader = FileFinder('/Users/razy69/Dev/Git/test39/./app')
Modified var:.. module_name = 'main'
11:29:20.267590 line       964                 if _is_module_ignored(module_name, ignored_modules):
11:29:20.267795 line       966                     ignored_modules.append(module_name)
11:29:20.267957 exception  966                     ignored_modules.append(module_name)
Exception:..... AttributeError: 'tuple' object has no attribute 'append'

@hellowhistler wrote a fix, but it is not merged:

Typer PR -> fastapi/typer#143 (review)

Hello,
I have a structure like this:

foo
`-- __init__.py
`-- common.py
`-- bar.py

where in bar.py I do import foo.common.
When running lazydocs, I get the message Failed to generate docs for module foo.bar: AttributeError("module 'foo' has no attribute 'common'",)

However, when just starting a new Python shell and doing import foo.bar there are no complaints, so I'd expect it to work in Lazydocs as well.

Anything that I'm missing, or is this a bug?

Describe the bug:

When using the function "generate_docs", if there are two files with the same name under different subpackages, (e.g. subpkg1/utils.py and subpkg2/utils.py), the docs generated for the second one will override the first "utils.py.md".

Expected behaviour:

Doc files are not to be overwritten.

Steps to reproduce the issue:

1. Have the following folder structure:
   src/subpkg1/utils.py
   src/subpkg2/utils.py
2. call generate_docs(["src/subpkg1/utils.py","src/subpkg2/utils.py"], "docs/")
3. Only one "docs/utils.py.md" is generated.

Technical details:

• Host Machine OS (Windows/Linux/Mac): Mac
• Browser (Chrome/Firefox/Safari): Irrelevant

Possible Fix:

Maybe add an option to name the file with the subpackage name as prefix (e.g. "docs/subpkg1.utils.py.md" and "docs/subpkg2.utils.py.md")

I run Python 3.10 on Debian 11:

lazydocs --output-path="./docs/lazydocs" --overview-file="README.md" --src-base-url="https://github.com/ronny-rentner/ultraimport/blob/main/" --no-watermark .
Generating docs for python package at: .
/usr/lib/python3/dist-packages/setuptools/config/pyprojecttoml.py:108: _BetaConfiguration: Support for `[tool.setuptools]` in `pyproject.toml` is still *beta*.
  warnings.warn(msg, _BetaConfiguration)
usage: lazydocs [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: lazydocs --help [cmd1 cmd2 ...]
   or: lazydocs --help-commands
   or: lazydocs cmd --help

error: option --output-path not recognized

It works if I exclude setup.py:

lazydocs --output-path="./docs/lazydocs" --overview-file="README.md" --src-base-url="https://github.com/ronny-rentner/ultraimport/blob/main/" --no-watermark --ignored-modules="setup" .
Generating docs for python package at: .
Writing ultraimport.md.
Writing README.md.
Writing mkdocs .pages file.

Shouldn't setup.py be excluded automatically? What's the point in generating documentation for it?

Describe the bug:
Decimal points are missed in default float values.

For example, if I have a function def foo(x = 0.01):, the docs will show x = 01. The markdown generator is unable to handle floating point default values.

Expected behaviour:

I expect my default floating point values to show up how I specified them in the code.

Steps to reproduce the issue:

For example, for the following function:

def foo(x : float = 0.01, y : int = 2) -> float:
    """Some function.

    Args:
        x (float, optional): A float number. Defaults to 0.01.
        y (int, optional): An integer. Defaults to 2.

    Returns:
        float: Their product.
    """     

    return x * y

Lazydoc renders it as:

Note the x=01, missing the ".".

Technical details:

• Host Machine OS (Windows/Linux/Mac): Linux
• Browser (Chrome/Firefox/Safari): Firefox

Possible Fix:

Most likely there isn't any floating point support, or something's missing somewhere. I believe this should be an easy fix.

Additional context:

Describe the bug:

Relative imports not supported: ImportError('attempted relative import beyond top-level package')

src/
    foo/
        __init__.py
        file_1.py
        file_2.py
    bar/
        __init__.py
        file_3.py
        file_4.py

In my files, I have all relative imports like: from ..bar import Spam, Eggs.

Expected behaviour:

Support relative imports. For example, the pdoc and pydoc-markdown packages work fine with my imports.

lazydocs just generates everything after Example: in same line, unlike Args: or Retruns:

def bits(n: int) -> int:
    '''
    returns bit-length of n

    Example:
        Of biggest RSA number.
    ```
        >>> bits(rsa[-1][1])
        2048
        >>>
    ```
    '''
    return int(log2(n) + 1)

Problem and motivation:

Adding Examples in doc is important.

Is this something you're interested in working on?

No experience with act.

But I built a Makefile workaround:

...
docs/RSA_numbers_factored.py.md: RSA_numbers_factored.py
	lazydocs $<
	sed -i "s# \(\`\`\`\)\$$#\n\1#;s#\(\*\*Example.*:\*\*\)#\1\n#" $@
...

Running that sed command after lazydocs results in wanted nice output:

I see that no real changes were done in 2023 and 2022.
So is lazydocs still maintained?

Building docs for modules that contain dataclasses fail with:

AttributeError("module '<module name>' has no attribute '__create_fn__'")

The init representation from dataclasses is different than for normal classes.

The version string in _about.py is set to __version__ = "0.5.0-dev.bugfix"

This is causing a local install to fail:

pip install -e .
Defaulting to user installation because normal site-packages is not writeable
Obtaining file:///home/ronny/Projects/py/lazydocs
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Preparing editable metadata (pyproject.toml) ... done
Requirement already satisfied: typer in /home/ronny/.local/lib/python3.10/site-packages (from lazydocs===0.5.0-dev.bugfix) (0.7.0)
Requirement already satisfied: click<9.0.0,>=7.1.1 in /home/ronny/.local/lib/python3.10/site-packages (from typer->lazydocs===0.5.0-dev.bugfix) (8.1.3)
Building wheels for collected packages: lazydocs
  Building editable for lazydocs (pyproject.toml) ... done
  Created wheel for lazydocs: filename=lazydocs-0.5.0_dev.bugfix-0.editable-py3-none-any.whl size=7507 sha256=2e7e2db0870c4db46d7835ab7b0d332254a0bb1f77937c1e121d749bb2847329
  Stored in directory: /tmp/pip-ephem-wheel-cache-76bgkh38/wheels/be/58/4e/9b56ea8cf13cb4f82d2332c9d15c62432365e8066a6b70ac50
  WARNING: Built editable for lazydocs is invalid: Metadata 1.2 mandates PEP 440 version, but '0.5.0-dev.bugfix' is not
Failed to build lazydocs
ERROR: Could not build wheels for lazydocs, which is required to install pyproject.toml-based projects

If I change the version to __version__ = "0.5.0-dev" a local install does work:

pip install -e .
Defaulting to user installation because normal site-packages is not writeable
Obtaining file:///home/ronny/Projects/py/lazydocs
  Installing build dependencies ... done
  Checking if build backend supports build_editable ... done
  Getting requirements to build editable ... done
  Preparing editable metadata (pyproject.toml) ... done
Requirement already satisfied: typer in /home/ronny/.local/lib/python3.10/site-packages (from lazydocs==0.5.0.dev0) (0.7.0)
Requirement already satisfied: click<9.0.0,>=7.1.1 in /home/ronny/.local/lib/python3.10/site-packages (from typer->lazydocs==0.5.0.dev0) (8.1.3)
Building wheels for collected packages: lazydocs
  Building editable for lazydocs (pyproject.toml) ... done
  Created wheel for lazydocs: filename=lazydocs-0.5.0.dev0-0.editable-py3-none-any.whl size=7412 sha256=67d515b4c0123e874d03545f509f539d240f7096a6f48b4a764f1c3ec0ed1978
  Stored in directory: /tmp/pip-ephem-wheel-cache-ekjj5skk/wheels/be/58/4e/9b56ea8cf13cb4f82d2332c9d15c62432365e8066a6b70ac50
Successfully built lazydocs
Installing collected packages: lazydocs
  Attempting uninstall: lazydocs
    Found existing installation: lazydocs 0.5.0.dev0
    Uninstalling lazydocs-0.5.0.dev0:
      Successfully uninstalled lazydocs-0.5.0.dev0
Successfully installed lazydocs-0.5.0.dev0

Describe the bug:

While trying to run it against the python directory I am getting an import error for get_terminal_size. Is there any way to sort out this error.

Error Screenshot

Technical details:

• Host Machine OS (Windows/Linux/Mac): Windows
• Browser (Chrome/Firefox/Safari): Chrome

Possible Fix:

Additional context:

Describe the bug:

When the return type is tuple, it is being rendered as "uple" instead.

Expected behaviour:
I expect it to show tuple.

Steps to reproduce the issue:

def foo(x : int = 1, y: int = 2, z: tuple = (0.001, 2)) -> tuple:
    """Some function.

    Args:
        x (int, optional): An integer. Defaults to 1.
        y (int, optional): An integer. Defaults to 2.
        z (tuple, optional): Tuple. Defaults to (0.001, 2).

    Returns:
        tuple: (x, y).
    """     
    return (x, y)

Lazydoc renders this as:

Note the "uple".

Technical details:

• Host Machine OS (Windows/Linux/Mac): Linux
• Browser (Chrome/Firefox/Safari): Firefox

Possible Fix:
Again, seems to be a cosmetic issue like #18

Additional context:

Hey!

I just came across an issue with the following environment:
I'm on Windows 10 and my python files are placed on a network volume (R:). Im calling lazydocs as an external tool from PyCharm. Therefore the path given to lazydocs starts with the drive letter. This all works fine until I initialise git. After this the docs creation fails. I think, the the reason are those lines:

The git command returns the path as UNC.

os.path.relpath(path, src_root_path) tries to combine the path with a drive letter with the unc path which does not work.

Maybe the src_root_path could also be set via the cli? In that case the git command wouldn't run and the path would always start with the drive letter.

Thanks,
Claus

These two lines

should read lazydocs.

Feature description:

Great tool! Thanks for publishing! Would you take a PR to make the src attribute of _SOURCE_BADGE_TEMPLATE configurable?

Problem and motivation:

Not a huge fan of the style=flat-square nor the cccccc color.

Is this something you're interested in working on?

Yes but not sure about timeline atm.

Hey,

After installing lazydocs for Python 3.12 im getting this error:

lazydocs --overview-file README.md --src-base-url="https://github.com/xx/xx-xx/blob/main/" xx/xx
Generating docs for python package at: internal_tools/internal_tools
Failed to generate docs for module xx: AttributeError("'FileFinder' object has no attribute 'find_module'")
Failed to generate docs for module xx: AttributeError("'FileFinder' object has no attribute 'find_module'")
Failed to generate docs for module xxx: AttributeError("'FileFinder' object has no attribute 'find_module'")
Writing README.md.
Writing mkdocs .pages file.

On Python 3.11 everything works fine.

Feature description:

Instead of creating several md files for each module, lazydocs create one single page with everything in there.

Problem and motivation:

I am currently working on several small projects that might have 2-4 functions per file. I want to gather all the documentation in a single page where I can easily find the module/function/class I want to without jumping from one page to the other.

Is this something you're interested in working on?

Probably no, due to lack of lazydocs code experience.

Describe the bug:

LaTeX code with backslashes in a Markdown docstring in Python does not render properly in GitHub.

Expected behaviour:

The README highlights lazydocs as compatible with Github Markdown, so the expected behaviour is that a Markdown documentation page generated from a Python docstring using lazydocs will render properly in GitHub, including all Markdown features that are supported on GitHub, including LaTeX. However, natural LaTeX code (with a natural/single number of backslashes) does not work reliably in the lazydoc output when viewed on GitHub.

Steps to reproduce the issue:

1. Create a blank python file with just the following docstring:

"""The vector $\mathbf{x}$ when written with a single backslash and works, but specifying a $3 \times 3$ matrix with a single backslash fails.

Specifying a $3 \\times 3$ matrix with a double-backslash works, and specifying the vector $\\mathbf{x}$ with a double-backslash also works."""

2. Run lazydocs and push to GitHub.
3. View the generated documentation Markdown file in GitHub and observe that the natural LaTeX code (with a single backslash) sometimes fails, e.g. at $3 \times 3$ on the first line. (It is supposed to look like on the second line.)

Technical details:

• Host Machine OS (Windows/Linux/Mac): Mac for viewing GitHub; lazydoc ran on Debian GNU/Linux 11 (bullseye)
• Browser (Chrome/Firefox/Safari): Chrome (outdated, 96.0.4664.110)

Possible Fix:

Additional context:

It would be extremely useful for documenting mathematics implemented in Python code (e.g. machine learning, etc.) for LaTeX to work properly in the documentation without need for modifying the number of backslashes, so that the LaTeX code can be retained properly within the code files.

Hi,

My package structure looks like this

.
├── README.md
├── __init__.py
├── apps.py
├── bronze
│   ├── GoogleAnalytics
│   │   └── __init__.py
│   ├── __init__.py
│   └── __pycache__
├── config.yml
├── main.py
├── raw
│   ├── GoogleAnalytics
│   │   └── __init__.py
│   ├── KafkaTopicRawLoader.py
│   ├── __init__.py
│   └── __pycache__
├── silver
│   ├── GoogleAnalytics
│   │   └── __init__.py
│   ├── __init__.py
│   └── __pycache__
└──  tools
    ├── __init__.py
    ├── __pycache__
    ├── boto3_handler.py
    ├── config_handler.py
    ├── dataframe_tools.py
    ├── deltalake_handler.py
    ├── kafka_handler.py
    ├── logging_tools.py
    └── spark_handler.py

Where I run lazydocs it puts all of the modules into a single directory

.
├── apps.md
├── bronze.GoogleAnalytics.md
├── bronze.md
├── main.md
├── raw.GoogleAnalytics.md
├── raw.KafkaTopicRawLoader.md
├── raw.md
├── silver.GoogleAnalytics.md
├── silver.md
├── tools.boto3_handler.md
├── tools.dataframe_tools.md
├── tools.deltalake_handler.md
├── tools.kafka_handler.md
├── tools.logging_tools.md
├── tools.md
└── tools.spark_handler.md

These are rendered in mkdocs without nesting. It would be great if there would be an option to create these files into nested directories instead of . style.

If a module has a sub-module there are show as Global Variables instead of sub-modules.

While pdoc3 renders this like this with a link to the sub-module, it would be great if lazydocs would be able to create links between as well and show the submodule docstring like pdoc3 can:

Feature description:

Support basic (unfenced) code blocks via indentation (at least 4 spaces or a tab), as per https://www.markdownguide.org/basic-syntax/#code-blocks.

I haven't looked at the lazydocs code, so I don't know whether or not this is a bug. Given what I've seen via some experimentation (not detailed here), it appears that this may be something currently not implemented, rather than a bug, but that's just an educated guess from what I'm seeing as output, not from looking at the code.

Problem and motivation:

Including doctests in docstrings can be extremely valuable (ref: https://docs.python.org/3/library/doctest.html), but lazydocs does not recognize them, and thus does not handle them specially, so they are not rendered properly if they are not somehow distinguished from surrounding text.

This should work in 2 ways, without the need for any special handling: (a) place doctests within a fenced code block, or (b) place them within a plain (unfenced), indented block (at least 4 spaces or a tab) indented from the surrounding text.

Unfortunately, neither works with lazydocs. Plain, unfenced, indented blocks are not recognized at all, and are simply treated as any other text, indented or not. Fenced code blocks don't work when they contain >>> (see #79).

For example, this docstring:

"""Compute the sum of 2 numbers.

Examples:

    >>> add(1, 2)
    3
    >>> add(2, 2)
    4
"""

Should generate markdown similar to the following:

Compute the sum of two numbers. 



**Examples:**
 

    >>> add(1, 2)
    3
    >>> add(2, 2)
    4

Instead, this is what is generated:

Compute the sum of two numbers. 



**Examples:**
 

``` add(1, 2)```
     3
     >>> add(2, 2)
     4

Is this something you're interested in working on?

yes, although I'll likely need some pointers on getting started

Feature description:

Add an option to prefix source url with ".py" before # (implementation possible at src/lazydocs/generation.py: _get_src_path()) and remove ".md" extensions from overview file. As such when correct base url is provided, it would also support GitLab.
Alternatively: add an option to select which git provider to use.

Problem and motivation:

This feature would provide support for GitLab projects and perhaps more.

Feature description:
The current implementation only links to lines using the Github style notation of #Lxx, while Bitbucket uses a more simple #xx, the feature should default to the current pattern, but allowed to be optionally passed in to override it for better support outside of Github.

Problem and motivation:
I am currently finding and replacing the pattern after the files are generated because I love the functionality of this library, so this would be a nice way to eliminate the need to hack the files up.

Describe the bug:

Global variable comment is ignored for lazydocs output.

Expected behaviour:

In gobal variables section, global variable comment should show as function comment shows for functions.

Steps to reproduce the issue:

Run lazydocs on glob.py:

glob = "foobar"
"""
    global string value
"""
glob2 = "foobar2"
"""
    global string value2
"""

def f() -> str:
    """
    returns:
        some string
    """
    return glob

"global string ..." comments do not show in generated lazydocs output:

Technical details:

Possible Fix:

Additional context:

When I look at the generated code, it contains a lot of HTML without any necessity for it, e. g. my parameters are rendered like this

 - <b>`use_cache`</b> (bool):  If set to `False`, allows re-importing of the same source file even if it was imported before.

which renders to

• use_cache (bool): If set to False, allows re-importing of the same source file even if it was imported before.

but it should be

 - **`use_cache`** (bool):  If set to `False`, allows re-importing of the same source file even if it was imported before.

which renders to the same result with no HTML:

• use_cache (bool): If set to False, allows re-importing of the same source file even if it was imported before.

After all the point of markdown is that the file renders nicely in a web browser but is at the same time easy and natural to read in an ascii text editor.

Feature description:

Add ability to add comment for generated lazydocs output between functions.

Problem and motivation:

Allows to structure groups of functions.

Is this something you're interested in working on?

No experience with act.

What I did sofar is to use dummy function definitions to achieve the requested feature as workaround:

...
    return int(lcm(p-1, q-1))


def SECTION5():
    '''
    Functions on factorization dictionaries.

    [as returned by sympy.factorint() (in rsa[x][4] for p-1 and rsa[x][5] for q-1) ]
    '''
    return
def dict_int(d):
...

This works, but creates a dummy function for each inter function comment, and one has to remember to have the final return.