Load Python objects documentation.
Load Python objects documentation.
With pip
:
pip install pytkdocs
With pipx
:
python3.7 -m pip install --user pipx
pipx install pytkdocs
With conda
:
conda install -c conda-forge pytkdocs
pytkdocs
accepts JSON on standard input and writes JSON on standard output.
Input format:
{
"objects": [
{
"path": "pytkdocs",
"new_path_syntax": false,
"members": true,
"inherited_members": false,
"filters": [
"!^_[^_]"
],
"docstring_style": "google",
"docstring_options": {
"replace_admonitions": true
}
}
]
}
Output format:
{
"loading_errors": [
"string (message)"
],
"parsing_errors": {
"string (object)": [
"string (message)"
]
},
"objects": [
{
"name": "pytkdocs",
"path": "pytkdocs",
"category": "module",
"file_path": "/media/data/dev/pawamoy/pytkdocs/src/pytkdocs/__init__.py",
"relative_file_path": "pytkdocs/__init__.py",
"properties": [
"special"
],
"parent_path": "pytkdocs",
"has_contents": true,
"docstring": "pytkdocs package.\n\nLoad Python objects documentation.",
"docstring_sections": [
{
"type": "markdown",
"value": "pytkdocs package.\n\nLoad Python objects documentation."
}
],
"source": {
"code": "\"\"\"\npytkdocs package.\n\nLoad Python objects documentation.\n\"\"\"\n\nfrom typing import List\n\n__all__: List[str] = []\n",
"line_start": 1
},
"children": {
"pytkdocs.__all__": {
"name": "__all__",
"path": "pytkdocs.__all__",
"category": "attribute",
"file_path": "/media/data/dev/pawamoy/pytkdocs/src/pytkdocs/__init__.py",
"relative_file_path": "pytkdocs/__init__.py",
"properties": [
"special"
],
"parent_path": "pytkdocs",
"has_contents": false,
"docstring": null,
"docstring_sections": [],
"source": {},
"children": {},
"attributes": [],
"methods": [],
"functions": [],
"modules": [],
"classes": []
}
},
"attributes": [
"pytkdocs.__all__"
],
"methods": [],
"functions": [],
"modules": [
"pytkdocs.__main__",
"pytkdocs.cli",
"pytkdocs.loader",
"pytkdocs.objects",
"pytkdocs.parsers",
"pytkdocs.properties",
"pytkdocs.serializer"
],
"classes": []
}
]
}
Running pytkdocs
without argument will read the whole standard input,
and output the result once.
Running pytkdocs --line-by-line
will enter an infinite loop,
where at each iteration one line is read on the standard input,
and the result is written back on one line.
This allows other programs to use pytkdocs
in a subprocess,
feeding it single lines of JSON, and reading back single lines of JSON as well.
This mode was actually implemented specifically for
mkdocstrings.
The configuration options available are:
new_path_syntax
: when set to true, this option forces the use of the new object path syntax,
which uses a colon (:
) to delimit modules from other objects.
filters
: filters are regular expressions that allow to select or un-select objects based on their name.
They are applied recursively (on every child of every object).
If the expression starts with an exclamation mark,
it will filter out objects matching it (the exclamation mark is removed before evaluation).
If not, objects matching it are selected.
Every regular expression is performed against every name.
It allows fine-grained filtering. Example:
!^_
: filter out every object whose name starts with _
(private/protected)^__
: but still select those who start with two _
(class-private)!^__.*__$
: except those who also end with two _
(specials)members
: this option allows to explicitly select the members of the top-object.
If True
, select every members that passes filters. If False
, select nothing.
If it's a list of names, select only those members, and apply filters on their children only.
inherited_members
: true or false (default). When enabled, inherited members will be selected as well.
docstring_style
: the docstring style to use when parsing the docstring. google
, restructured-text
1 and numpy
2.
docstring_options
: options to pass to the docstring parser.
replace_admonitions
boolean option (default: true). When enabled, this option will
replace titles of an indented block by their Markdown admonition equivalent:
AdmonitionType: Title
will become !!! admonitiontype "Title"
.trim_doctest_flags
boolean option (default: true). When enabled, all doctest
flags (of the form # doctest: +FLAG
and <BLANKLINE>
) located within python
example blocks will be removed from the parsed output.The google
docstring style accepts both options. The numpy
style only accepts trim_doctest_flags
. The restructured-text
style does not accept any options.
1: reStructured Text parsing is in active development and is not feature complete yet.
2: The following sections are currently not supported : Notes
, See Also
, Warns
and References
.
new_path_syntax
Example:
New syntax | package.module:Class.attribute |
Old syntax | package.module.Class.attribute |
pytkdocs
splits the path accordingly,
regardless of the value of new_path_syntax
.new_path_syntax
is false, pytkdocs
uses the
old importing behavior.new_path_syntax
is true, pytkdocs
uses the new
importing behavior and therefore considers that the path points to a module.