davidenunes/mkgendocs

Markdown documentation generator from Google docstrings

mkgendocs's Issues

Add function return type

source

class Xxx():
    def get_xxx(self, arg: str) -> str:
        pass

actual

Xxx

Xxx()

---

Methods:

.get_xxx

.get_xxx(
   arg: str
)

expected

Xxx

Xxx()

---

Methods:

.get_xxx

.get_xxx(
   arg: str
) -> str

Dataclass attributes not documented

Hi

I tried using mkgendocs with a project that uses dataclasses, however the output was missing all of the dataclass attributes.

For example, the Context dataclass here:
https://github.com/heroku/sf-functions-python/blob/3d3b16abc76bde98718fa053f1226fdc4a7052f9/salesforce_functions/context.py#L36-L41

...was documented as:

## Context
\```python 
Context()
\```


---
Information relating to the function and the Salesforce org with which it is associated.

...the org attribute is missing, and also the Context() function signature is missing all arguments present in the generated constructor.

abstractmethod is not output

abstractmethod is not output.
Correctly in some classes with implementation.

https://docs.python.org/3/library/abc.html#abc.abstractmethod

RAM overuse

Hey,

So I built a python package and have documented the code using docstring but when I run the command gendocs --config mkgendocs.yml I face a RAM overuse until I have to kill the process. Cant really share the code due to NDA.

Has anyone else faced this issue? What might have caused this?

Not parsing dict examples from docstrings

There is a problem parsing dict examples in docstrings. For example if a have this docstring:

class FlowFactory(Flow):
    """
    Bla Bla Bla

    !!! example "Example of flow_init configuration"
        In the example below ...

            flow_init = {
                "app_mode": "TEST",
                "app_version": "1.0.0",
                "config_base_directory": "C:\\workspace\\test_env\\TEST",
                "env": "local",
                "jsons_dir": "<some_path>",
            }
    """

its not parsing that dict. The final result in online documentation is:

flow_init = {
}

I'm using Python 3.9 and latest version of this packages:

mkdocs  # static site generator for documentation in Markdown
mkgendocs  # generate MkDocs pages from Google-style docstrings of Python functions
mkdocs-material  # Material support for MkDocs
mkdocs-minify-plugin  # strips whitespaces in HTML markdown documentation pages
mkdocs-git-revision-date-localized-plugin  # displays the date of the last git modification of a markdown page
mkdocs-git-authors-plugin  # displays git authors of a markdown page
mkdocs-table-reader-plugin  # enables automatic CSV imports as a table into a markdown page
mkdocs-img2fig-plugin # converts markdown encoded images to HTML figures
mkdocs-awesome-pages-plugin # enables naive configuration of page titles and their order
mkdocs-enumerate-headings-plugin  # enumerates headings across markdown pages
mkdocs-print-site-plugin  # allows visiters to File > Print > Save as PDF entire markdown documentation

Unable to find async functions

Love the tool, using it for a few projects.

Ran into this today that is pretty straightforward, I would surmise that async def func_name() was not included in scope for the original development.

If i can provide more data or details, please let me know!

Reproduction of Error

main.py

async def a_func() ->> bool:
    """ A Test Func
    
    Returns:
        bool: Returns True always
    """
    return True

mkgendocs.yml

---
sources_dir: docs
version: main

pages:
  - page: main.md
    source: main.py
    functions:
      - a_func

GenDocs (Fail)

% gendocs --config mkgendocs.yml
>Loading configuration file
>Cleaning up existing sources directory.
>Populating sources directory with templates.
>Generating docs ...
>Building ref index...
>Generating docs for a_func
Traceback (most recent call last):
  File "/Users/user/git/project_repository/env/bin/gendocs", line 8, in <module>
    sys.exit(main())
  File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/gendocs.py", line 412, in main
    generate(args.config)
  File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/gendocs.py", line 379, in generate
    fn_info = extract.get_function(fn)
  File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/parse.py", line 637, in get_function
    fn = self._get_function(function_name)
  File "/Users/user/git/project_repository/env/lib/python3.10/site-packages/mkgendocs/parse.py", line 681, in _get_function
    raise Exception("function %s not found in %s" % (function_name, self.path))
Exception: function a_func not found in /Users/user/git/project_repository/main.py

Modify main.py (remove async)

def a_func() ->> bool:
    """ A Test Func
    
    Returns:
        bool: Returns True always
    """
    return True

GenDocs (Succeed)

% gendocs --config mkgendocs.yml
>Loading configuration file
>Cleaning up existing sources directory.
>Populating sources directory with templates.
>Generating docs ...
>Building ref index...
>Generating docs for a_func
>Creating new page with autogenerated content:docs/main.md

Modular parser for other docstring types

The project looks amazing and I would really like to use it, but sadly I am using numpy docstrings for my documentation. When I have time, I would love to extend the project to support numpy docstrings too, but the code is quite long and it isn't obvious how to extend it properly. Do you have tips on where to start? Maybe the parsers could be implemented in separate files and then called upon depending on what is provided in the documentation 😄