davidenunes / mkgendocs Goto Github PK
View Code? Open in Web Editor NEWMarkdown documentation generator from Google docstrings
License: Apache License 2.0
Markdown documentation generator from Google docstrings
License: Apache License 2.0
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
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 ๐
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.
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?
abstractmethod is not output.
Correctly in some classes with implementation.
https://docs.python.org/3/library/abc.html#abc.abstractmethod
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!
async def a_func() ->> bool:
""" A Test Func
Returns:
bool: Returns True always
"""
return True
---
sources_dir: docs
version: main
pages:
- page: main.md
source: main.py
functions:
- a_func
% 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
def a_func() ->> bool:
""" A Test Func
Returns:
bool: Returns True always
"""
return True
% 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
class Xxx():
def get_xxx(self, arg: str) -> str:
pass
Xxx()
Methods:
.get_xxx(
arg: str
)
Xxx()
Methods:
.get_xxx(
arg: str
) -> str
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.