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.0a1.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 6ab2f5be663ca2b8bef838ccbaca251f8a4e965aa75a6c8483524d67eb5b5f87 |
|
MD5 | 3785a9f4b91796b0f6e11876cf1cf2a1 |
|
BLAKE2b-256 | e79c1203f58fde2b50e904fa57820edd7a8b76d1e5727ab370f415521ebee5ea |
Hashes for jetblack_markdown-1.2.0a1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | b1b294f2dc23ad962af024d615f1695266921bac75f51328771857ebc0c84d5f |
|
MD5 | 61325e59ed52ac33566cde0bc07b4f09 |
|
BLAKE2b-256 | d34a23617595214a69e97d40fe64dba7a3735e6a4f24e9ab7d9dd97024dd425a |