A markdown extension for python documentation
Project description
jetblack-markdown
Markdown extensions for automatic document generation (read the docs).
Autodoc Extension
A markdown extension is provided for automatically documenting python code.
Modules are referred to as follows:
# A Top Level Module
@[jetblack_markdown]
# A Package
@[jetblack_markdown.autodoc]
# A function
@[jetblack_markdown.autodoc:makeExtension]
# A class
@[jetblack_markdown.autodoc.metadata:PropertyDescriptor]
Customizing
All the rendering is done with jinja2 templates. Start by copying the current
templates from jetblack_markdown/templates and specify the template_folder
in
the mkdocs.yml
.
LaTex2MathML Extension
There is a second extension which transforms LeTax style math formula
to MathML HTML. Inline formula are surrounded by $
, which blocks are
fenced with $$
. See the documentation for more details and examples.
mkdocs integration
This site was generated using mkdocs
and the following config:
site_name: jetblack-markdown
docs_dir: documentation
site_dir: docs
markdown_extensions:
- admonition
- codehilite
- jetblack_markdown.autodoc:
class_from_init: true
ignore_dunder: true
ignore_private: true
ignore_all: false
prefer_docstring: true
template_folder: null
extra_css:
- css/custom.css
Configuration
There are some configuration parameters for the autodoc extension.
- class_from_init (bool, optional): If True use the docstring from the __init__ function for classes. Defaults to True.
- ignore_dunder (bool, optional): If True ignore __XXX__ functions. Defaults to True.
- ignore_private (bool, optional): If True ignore methods (those prefixed _XXX). Defaults to True.
- ignore_all (bool): If True ignore the __all__ member.
- prefer_docstring (bool): If true prefer the docstring.
- template_folder(Optional[str], optional): Specify a custom template folder.
The template "main.jinja2" will be rendered passing an
obj
parameter which is ajetblack.markdown.metadata.Descriptor
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for jetblack-markdown-1.2.0a0.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 827af65baeefb16723880f1cdd8f7c296d0bd671f5bbceaf3a295825106d7c12 |
|
MD5 | f584dc93d6ab542e07552967a3a4df87 |
|
BLAKE2b-256 | 0bf0de983a6f9ef1c5623ccc6db39f056ec107029ab285aa668091794bd924ac |
Hashes for jetblack_markdown-1.2.0a0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0e0cd88e435925bc6e9fd1278f3f994fa7ace5e6b2092af85d21f75f0dab32a1 |
|
MD5 | 292d902621c16f4e568e98d8ee8df822 |
|
BLAKE2b-256 | ae58e46a5e8059054e79d60bfdb222dda483b3e96ec6423389c8b8a5931f63e5 |