tomchristie / mkautodoc Goto Github PK
View Code? Open in Web Editor NEWAuto documentation for MkDocs ๐
Auto documentation for MkDocs ๐
Does this plugin support docstrings in numpydoc and/or Google style as Napoleon does for sphinx? Or can this be achieved in some other way?
With markdown installed in version 3.4 or newer, import mkautodoc
fails with
ImportError: cannot import name 'etree' from 'markdown.util'
The markdown.util.etree
import has been deprecated since version 3.0 and has been finally removed in version 3.4. It needs to be replaced with xml.etree.ElementTree
, cp. the changelog.
Hi @tomchristie! I'm finding the mkdocs ecosystem of packages to be quite a joy to use, and yours is part of it too!
I've been doing just a trial-run seeing whether we can make the PyMC4 docs from sphinx rather than mkdocs, and mkautodoc has been pretty cool. It does necessitate that I rewrite docstrings in markdown, but that's not a big issue.
One question I've got for you, just to see whether this is possible or not - do you know how we can have our classes and functions that are "top-level" defined in a module show up as part of the mkdocs-generated table of contents? In particular, I'm thinking of having them show up on the right hand side (like in the screenshot I have attached below):
At the moment, in the Markdown file, I have to do something like:
# PyMC4 Continuous Distributions
## Beta Distribution
::: pymc4.distributions.continuous.Beta
:docstring:
## Normal distribution
......
Instead, I'd like to be able to do something like:
# PyMC4 Continuous Distributions
::: pymc4.distributions.continuous
:docstring:
:members:
and still get the right-side TOC rendering from parsing the Markdown.
For the life of me I cannot get tables to render; is that a known issue?
Install the package using pip: pip install mkautodoc
.
Include it in mkdocs.yml
file under markdown_extensions
:
markdown_extensions:
- mkautodoc
Run mkdocs serve
command.
I encountered the following error message:
ERROR - Config value 'markdown_extensions': Failed to load extension 'mkautodoc'.
ModuleNotFoundError: No module named 'mkautodoc'
Aborted with 1 Configuration Errors!
Please let me know if there's any other information I can provide. Thank you!
My Python code is written using the Sphinx docstring format:
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html
:param [ParamName]: [ParamDescription], defaults to [DefaultParamVal]
:type [ParamName]: [ParamType](, optional)
...
:raises [ErrorType]: [ErrorDescription]
...
:return: [ReturnDescription]
:rtype: [ReturnType]
It would be really a great feature that mkautodoc detects it so that it format the doc such it is displayed on this repo home page.
Hello, thanks for wonderful tool!
Prettier is a very popular pretty printer tool. It could be used to format javascript, yaml, markdown, and a lot more file formats.
Unfortunately, it has compatibility issues with syntax proposed by this extension.
If I run prettier --write .
command it will change my document like this:
diff --git a/docs/reference.md b/docs/reference.md
index 3143ee2..fa4022d 100644
@@ -1,13 +1,10 @@
# Reference
::: generics.private
- :docstring:
+:docstring:
::: generics.delegated
- :docstring:
+:docstring:
::: generics.defended
- :docstring:
+:docstring:
<p align="center">— โญ —</p>
<p align="center"><i>The generics library is part of the SOLID python family.</i></p>
I I run prettier --prose-wrap=always --write .
commant it will change my document like this:
diff --git a/docs/reference.md b/docs/reference.md
index 3143ee2..fa4022d 100644
@@ -1,13 +1,10 @@
# Reference
-::: generics.private
- :docstring:
+::: generics.private :docstring:
-::: generics.delegated
- :docstring:
+::: generics.delegated :docstring:
-::: generics.defended
- :docstring:
+::: generics.defended :docstring:
<p align="center">— โญ —</p>
<p align="center"><i>The generics library is part of the SOLID python family.</i></p>
None of these variants is compatible with the auto doc extension provided by this package.
Similar extensions like admonitions works fine with prettier. For example, you can use in this way:
!!! note
Subtyping inheritance with `abc.Meta` is not implemented yet. We have plans to implement it in the future.
The result will look like this. Scroll up a little bit to see a note
Is there any way to make it work with prettier? If no, could you explain how could I could extend the project to achieve it? Happy to make a small pull request to make this happen.
Have a good day ๐ด
Best regards,
Artem.
Hi,
I am evaluating if the plugin would work for a python library, but I couldn't find any information which style it actually supports?
I only found issues regarding which styles it does not support, e.g. #25 and #23
So which is the actual style that the docstrings should have? Would be great to see this info and an example in the readme.
Thanks!
The :members:
keyword currently allows to retrict the properties and method that can be displayed in the doc by listing them.
Is it possible to have the ability to display all, except the one listed.
For example:
:members: !logger !get_stuff
where the !
explicitly tells not to display it
Is there a way to use not importable modules like in Sphinx with the autodoc_mock_imports list?
Does it support module documentation?
Hello,
looking at the code, it doesnt appear you declared any explicit copyright (as in a pair of and ) for this project, and even the specified license, BSD
, is more a family of licenses than a single license: can you clarify which BSB license this program is licensed as?
Hello,
Your project seems interesting but I don't see any reference to the style of Python docstring you can use like NumPy or Google...
Did I miss something?
Thanks!
Hi,
I'm working on a library using trio and when I want to build the documentation, I have the bad surprise that the backend is not supported.
My environment:
Ubuntu 18.04 LTS
Python 3.6
mkdocs 1.1.2
mkautodoc: 0.1.0
My traceback
mkdocs build
INFO - Cleaning site directory
INFO - Building documentation to directory: /home/kevin/PycharmProjects/open_source/scalpel/site
ERROR - Error reading page 'api.md': unsupported platform
Traceback (most recent call last):
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/bin/mkdocs", line 11, in <module>
sys.exit(cli())
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/click/core.py", line 829, in __call__
return self.main(*args, **kwargs)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/click/core.py", line 782, in main
rv = self.invoke(ctx)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/click/core.py", line 1259, in invoke
return _process_result(sub_ctx.command.invoke(sub_ctx))
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/click/core.py", line 1066, in invoke
return ctx.invoke(self.callback, **ctx.params)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/click/core.py", line 610, in invoke
return callback(*args, **kwargs)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/mkdocs/__main__.py", line 152, in build_command
build.build(config.load_config(**kwargs), dirty=not clean)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/mkdocs/commands/build.py", line 271, in build
_populate_page(file.page, config, files, dirty)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/mkdocs/commands/build.py", line 171, in _populate_page
page.render(config, files)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/mkdocs/structure/pages.py", line 175, in render
self.content = md.convert(self.markdown)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/markdown/core.py", line 263, in convert
root = self.parser.parseDocument(self.lines).getroot()
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/markdown/blockparser.py", line 90, in parseDocument
self.parseChunk(self.root, '\n'.join(lines))
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/markdown/blockparser.py", line 105, in parseChunk
self.parseBlocks(parent, text.split('\n\n'))
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/markdown/blockparser.py", line 123, in parseBlocks
if processor.run(parent, blocks) is not False:
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/mkautodoc/extension.py", line 153, in run
item = import_from_string(import_string)
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/mkautodoc/extension.py", line 20, in import_from_string
module = importlib.import_module(module_str)
File "/home/kevin/.pyenv/versions/3.6.10/lib/python3.6/importlib/__init__.py", line 126, in import_module
return _bootstrap._gcd_import(name[level:], package, level)
File "<frozen importlib._bootstrap>", line 994, in _gcd_import
File "<frozen importlib._bootstrap>", line 971, in _find_and_load
File "<frozen importlib._bootstrap>", line 955, in _find_and_load_unlocked
File "<frozen importlib._bootstrap>", line 665, in _load_unlocked
File "<frozen importlib._bootstrap_external>", line 678, in exec_module
File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
File "/home/kevin/PycharmProjects/open_source/scalpel/scalpel/trionic/__init__.py", line 1, in <module>
from .files import read_mp, write_mp
File "/home/kevin/PycharmProjects/open_source/scalpel/scalpel/trionic/files.py", line 6, in <module>
import trio
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/trio/__init__.py", line 18, in <module>
from ._core import (
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/trio/_core/__init__.py", line 27, in <module>
from ._run import (
File "/home/kevin/.cache/pypoetry/virtualenvs/scalpel-WzXLQS4X-py3.6/lib/python3.6/site-packages/trio/_core/_run.py", line 2325, in <module>
raise NotImplementedError("unsupported platform")
NotImplementedError: unsupported platform
Tell me if you want more information.
Best regards
In Sphinx / reStructuredText you can reference other methods / classes with :meth:`~module.class.method`
or :class:`module.class`
. Is there a way to do the same with Markdown docstrings? If not, do you plan to add support for it?
I am trying to incorporate mkautodoc to my project which is based on django and django-rest-framework. I believe before mkautodoc can properly work, django.setup()
has to be called.
Any advice on how to do this?
If I just include mkautodoc and try to create a docstring mkdocs crashes with:
django.core.exceptions.ImproperlyConfigured: Requested setting REST_FRAMEWORK, but settings are not configured. You must either define the environment variable DJANGO_SETTINGS_MODULE or call settings.configure() before accessing settings.
It seems obvious but I prefer to make sure ๐
I am trying to create a documentation using your plugin and mkdocs. I have material theme installed. My code is the following:
class MyClass(MyBaseClass):
"""
Client to connect synchronously with diamant
"""
def __init__(self, builder: "MyClass.Builder"):
"""
This is the synchronous version of the client.
:param MyClass.Builder builder: Builder object to build
client
"""
super().__init__(base_url=url)
self.__api_token = builder.api_token
self.__connection_timeout = builder.connection_timeout
self.__read_timeout = builder.read_timeout
md file
::: mymodule.MyClass
:docstring:
mkdocs.yml
markdown_extensions:
- extra
- admonition
- mkautodoc
- pymdownx.caret
- pymdownx.critic
- pymdownx.superfences
- codehilite:
linenums: true
guess_lang: false
- toc:
permalink: ๐
- pymdownx.emoji:
emoji_generator: !!python/name:pymdownx.emoji.to_svg
When running mkdocs serve
page is rendered normally with class definition but with two issues:
class mymodle.MyClass
(builder) is the only think that is rendered.
Is there as particular way to write docstring to use your plugin?
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.