# jetblack-markdown
Markdown extensions for automatic document generation
(read the [docs](https://rob-blackbourn.github.io/jetblack-markdown/)).
## Markdown Extension
A markdown extension is provided for automatically documenting python code.
Modules are referred to as follows:
```markdown
# A Top Level Module
@[jetblack_markdown]
# A Package
@[jetblack_markdown.autodoc]
# A function
@[jetblack_markdown.autodoc:makeExtension]
# A class
@[jetblack_markdown.autodoc.metadata:PropertyDescriptor]
```
## mkdocs integration
This site was generated using `mkdocs` and the following config:
```yaml
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.
* 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 a `jetblack.markdown.metadata.Descriptor`
## 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`.
Raw data
{
"_id": null,
"home_page": "https://github.com/rob-blackbourn/jetblack-markdown",
"name": "jetblack-markdown",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7,<4.0",
"maintainer_email": "",
"keywords": "",
"author": "Rob Blackbourn",
"author_email": "rob.blackbourn@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bb/1a/60c28c0ff5a5ae60a772954bc840e9a6e1bed9c61ebabd3d8e532def33fd/jetblack-markdown-1.1.0.tar.gz",
"platform": null,
"description": "# jetblack-markdown\n\nMarkdown extensions for automatic document generation\n(read the [docs](https://rob-blackbourn.github.io/jetblack-markdown/)).\n\n## Markdown Extension\n\nA markdown extension is provided for automatically documenting python code.\n\nModules are referred to as follows:\n\n```markdown\n# A Top Level Module\n\n@[jetblack_markdown]\n\n# A Package\n\n@[jetblack_markdown.autodoc]\n\n# A function\n\n@[jetblack_markdown.autodoc:makeExtension]\n\n# A class\n\n@[jetblack_markdown.autodoc.metadata:PropertyDescriptor]\n```\n\n## mkdocs integration\n\nThis site was generated using `mkdocs` and the following config:\n\n```yaml\nsite_name: jetblack-markdown\n\ndocs_dir: documentation\nsite_dir: docs\n\nmarkdown_extensions:\n - admonition\n - codehilite\n - jetblack_markdown.autodoc:\n class_from_init: true\n ignore_dunder: true\n ignore_private: true\n ignore_all: false\n prefer_docstring: true\n template_folder: null\n\nextra_css:\n - css/custom.css\n```\n\n### Configuration\n\nThere are some configuration parameters.\n\n* class_from_init (bool, optional): If True use the docstring from\n the __init__ function for classes. Defaults to\n True.\n* ignore_dunder (bool, optional): If True ignore\n __XXX__ functions. Defaults to True.\n* ignore_private (bool, optional): If True ignore methods\n (those prefixed _XXX). Defaults to True.\n* ignore_all (bool): If True ignore the __all__ member.\n* prefer_docstring (bool): If true prefer the docstring.\n* template_folder(Optional[str], optional): Specify a custom template folder.\n The template \"main.jinja2\" will be rendered passing an `obj` parameter\n which is a `jetblack.markdown.metadata.Descriptor`\n\n## Customizing\n\nAll the rendering is done with jinja2 templates. Start by copying the current\ntemplates from jetblack_markdown/templates and specify the `template_folder` in\nthe `mkdocs.yml`.\n\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A markdown extension for python documentation",
"version": "1.1.0",
"project_urls": {
"Homepage": "https://github.com/rob-blackbourn/jetblack-markdown",
"Repository": "https://github.com/rob-blackbourn/jetblack-markdown"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c3321ba07dbef48f30d6da1e544c1ab7703e9e05f94dd4ec82e343a2ca5ba4c1",
"md5": "557cee370913639a2195b37e3bf1b443",
"sha256": "fbc134e02913bc2801dcf6c9e63d8e9f7dcff6d9c8df02c666b2c434dc303e13"
},
"downloads": -1,
"filename": "jetblack_markdown-1.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "557cee370913639a2195b37e3bf1b443",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7,<4.0",
"size": 21224,
"upload_time": "2022-09-24T07:48:11",
"upload_time_iso_8601": "2022-09-24T07:48:11.558106Z",
"url": "https://files.pythonhosted.org/packages/c3/32/1ba07dbef48f30d6da1e544c1ab7703e9e05f94dd4ec82e343a2ca5ba4c1/jetblack_markdown-1.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb1a60c28c0ff5a5ae60a772954bc840e9a6e1bed9c61ebabd3d8e532def33fd",
"md5": "7454bbeae824e131935031c21056ba7b",
"sha256": "dcd4a8a8a7a3177e478aca9655a7d5eadbf4677063406b4d6e52661f191f665d"
},
"downloads": -1,
"filename": "jetblack-markdown-1.1.0.tar.gz",
"has_sig": false,
"md5_digest": "7454bbeae824e131935031c21056ba7b",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7,<4.0",
"size": 14109,
"upload_time": "2022-09-24T07:48:09",
"upload_time_iso_8601": "2022-09-24T07:48:09.608527Z",
"url": "https://files.pythonhosted.org/packages/bb/1a/60c28c0ff5a5ae60a772954bc840e9a6e1bed9c61ebabd3d8e532def33fd/jetblack-markdown-1.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2022-09-24 07:48:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "rob-blackbourn",
"github_project": "jetblack-markdown",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "jetblack-markdown"
}
JSON
