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.0a3.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5c4bcb08171ee6075e4ea0a0a60cab32d9900247d17b40fb37689ff2d2a51aec |
|
MD5 | 27766968cd37d068ddc6f2ce858016e6 |
|
BLAKE2b-256 | 8d0518bc442da3a21ad7bb89a2171163ac29a0d5efc0b0ea8e4fb43df790d836 |
Hashes for jetblack_markdown-1.2.0a3-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 49a88d4c0bcd956738b9eb9ffc5ac6ab4245cf8595aad1d227b091b02189bfd0 |
|
MD5 | 6b1887c811cdd4b076833feab6671275 |
|
BLAKE2b-256 | ac07246c6357249a0744a19f3eacc1bece08ed5b5f9666e2e3b9a0d8808afad8 |