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.0a4.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | d7f1a2e5ff2b434b2d92e91e5ff8847bf931b3630c7687bbd741d7395a08954a |
|
MD5 | d6e455ab280642a6495a63b8d9b24911 |
|
BLAKE2b-256 | 8aa7d60dcd4705a22b5519b39b2dedb34afa3062a028f527aa89387d2464445d |
Hashes for jetblack_markdown-1.2.0a4-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0b76110b4793984852c0dffe87f673617f5c016637bf7280e23205b36c582deb |
|
MD5 | a7c412bd4b104f34adcb79010e7edb6c |
|
BLAKE2b-256 | 4bb1d81f2ec1605c5d0f4d721915c060654500ddb4247a2d00eb35fd6f13406f |