tomchristie / mkautodoc

Auto documentation for MkDocs 📘

MkAutoDoc

Python API documentation for MkDocs.

This markdown extension adds autodoc style support, for use with MkDocs.

Usage

1. Include the extension in you mkdocs.yml config file:

[...]
markdown_extensions:
  - admonition
  - codehilite
  - mkautodoc

2. Ensure the library you want to document is importable.

This will depend on how your documentation building is setup, but you may need to use pip install -e . or modify PYTHONPATH in your docs build script.

3. Use the ::: block syntax to add autodoc blocks to your documentation.

# API documentation

::: my_library.some_function
    :docstring:

::: my_library.SomeClass
    :docstring:
    :members:

4. Optionally, add styling for the API docs

Update your mkdocs.yml to include some custom CSS.

[...]
extra_css:
    - css/custom.css

Then add a css/custom.css file to your documentation.

div.autodoc-docstring {
  padding-left: 20px;
  margin-bottom: 30px;
  border-left: 5px solid rgba(230, 230, 230);
}

div.autodoc-members {
  padding-left: 20px;
  margin-bottom: 15px;
}

Notes

The :docstring: declaration.

Renders the docstring of the associated function, method, or class.

The :members: declaration.

Renders documentation for member attributes of the associated class. Currently handles methods and properties. Instance attributes set during __init__ are not currently recognised.

May optionally accept a list of member attributes that should be documented. For example:

::: my_library.SomeClass
    :docstring:
    :members: currency vat_registered calculate_expenses

mkautodoc's Issues

Failed to load extension 'mkautodoc'

Steps to Reproduce

1. Install the package using pip: pip install mkautodoc.

2. Include it in mkdocs.yml file under markdown_extensions:

   markdown_extensions:
     - mkautodoc

3. 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!

Additional Information

• Operating System: Linux
• Python Version: 3.8.0, error is also reproducable with 3.11.3
• mkautodoc Version: 0.2.0

Please let me know if there's any other information I can provide. Thank you!

:members: : select all, except the one specified

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

Support references

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?

Please clarify copyright and licence

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?

mkautodoc does not support trio library

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

Incompatible with prettier.

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">&mdash; ⭐ &mdash;</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">&mdash; ⭐ &mdash;</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.

TOC from rendered docs?

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.

Support for different docstring styles?

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?

Table rendering

For the life of me I cannot get tables to render; is that a known issue?

Which docstring style is supported?

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!

Incompatible with markdown >=3.4

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.

Docstring format supported ?

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!

Mock imports

Is there a way to use not importable modules like in Sphinx with the autodoc_mock_imports list?

Question: must docstrings be written in markdown?

It seems obvious but I prefer to make sure 😉

Integration with a django project

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.

Support module documentation

Does it support module documentation?

Docstrings aren't rendered at all

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:

1. No types on the constructor parameters (builder doesn't get a type)
2. No docstrings are rendered

class mymodle.MyClass(builder) is the only think that is rendered.
Is there as particular way to write docstring to use your plugin?

Feature: Format using Sphinx docstring format

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.