diff --git a/CHANGELOG.md b/CHANGELOG.md index d867b41c..1444a814 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,8 @@ # Changelog ## [Unreleased] + +## [1.0.8] - 2020-06-20 ### Added - `short` filter to remove the prefix from an object name. ([#16](https://github.com/daizutabi/mkapi/pull/16)). Thanks to [Ahrak](https://github.com/Ahrak). diff --git a/docs/usage/inherit.md b/docs/usage/inherit.md index 5f829071..3a2a9857 100644 --- a/docs/usage/inherit.md +++ b/docs/usage/inherit.md @@ -27,6 +27,7 @@ Taking a look at this example, you may notice that: * In the `Base`, there is no description for `type`. * In the `Item`, parameters inherited from the superclass are not written. * In the `Item.set_name()`, Parameters section itself doesn't exist. +* In the `Base.set()`, `{class}` variable is used to replace it by class name. ## Inheritance from Superclasses diff --git a/docs/usage/library.py b/docs/usage/library.py index 4a210a1e..5858ae5c 100644 --- a/docs/usage/library.py +++ b/docs/usage/library.py @@ -57,10 +57,10 @@ def to_str(self, x: int) -> str: len(docstring.sections) # type:ignore # - section = docstring.sections[0] # type:ignore -section.name, section.markdown +section.name +# - +print(section.markdown) # - -section = docstring.sections[1] # type:ignore -section.name, section.markdown # The `members` attribute gives children, for example, bound methods of a class. @@ -108,7 +108,7 @@ def to_str(self, x: int) -> str: from markdown import Markdown # isort:skip -converter = Markdown() +converter = Markdown(extensions=['admonition']) html = converter.convert(markdown) print(html) diff --git a/examples/inherit.py b/examples/inherit.py index c2e40bb6..a80c9b58 100644 --- a/examples/inherit.py +++ b/examples/inherit.py @@ -25,6 +25,10 @@ def set_name(self, name: str): """ self.name = name + def get(self): + """Returns {class} instace.""" + return self + @dataclass class Item(Base): diff --git a/mkapi/__init__.py b/mkapi/__init__.py index 0c462f8b..bedc767c 100644 --- a/mkapi/__init__.py +++ b/mkapi/__init__.py @@ -1,4 +1,4 @@ -__version__ = "1.0.7" +__version__ = "1.0.8" from mkapi.core.module import get_module from mkapi.core.node import get_node diff --git a/mkapi/core/attribute.py b/mkapi/core/attribute.py index fb3575a8..0ab1ca45 100644 --- a/mkapi/core/attribute.py +++ b/mkapi/core/attribute.py @@ -1,4 +1,4 @@ -"""This module provides attributes inspection from source code.""" +"""This module provides functions that inspect attributes from source code.""" import ast import importlib import inspect @@ -90,8 +90,6 @@ def get_description(lines: List[str], lineno: int) -> str: return "\n".join(docs).strip() elif in_doc: docs.append(line) - if docs: - return "\n".join(docs).strip() return "" diff --git a/mkapi/core/module.py b/mkapi/core/module.py index 032e93c0..9d7bec7e 100644 --- a/mkapi/core/module.py +++ b/mkapi/core/module.py @@ -11,7 +11,7 @@ @dataclass(repr=False) class Module(Tree): - """Module class represents an module. + """Module class represents a module. Attributes: parent: Parent Module instance. diff --git a/mkapi/core/postprocess.py b/mkapi/core/postprocess.py index dac53819..c19b3176 100644 --- a/mkapi/core/postprocess.py +++ b/mkapi/core/postprocess.py @@ -128,8 +128,6 @@ def sort(node: Node): def transform(node: Node, filters: Optional[List[str]] = None): - if node.docstring is None: - return if node.object.kind in ["class", "dataclass"]: transform_class(node, filters) elif node.object.kind in ["module", "package"]: diff --git a/mkapi/core/preprocess.py b/mkapi/core/preprocess.py index 933586a9..8e5efd56 100644 --- a/mkapi/core/preprocess.py +++ b/mkapi/core/preprocess.py @@ -60,6 +60,6 @@ def admonition(name: str, markdown: str) -> str: type = "warning" else: type = name.lower() - lines = [" " + line for line in markdown.split("\n")] + lines = [" " + line if line else "" for line in markdown.split("\n")] lines.insert(0, f'!!! {type} "{name}"') return "\n".join(lines) diff --git a/mkapi/core/renderer.py b/mkapi/core/renderer.py index da2c559d..e7dde340 100644 --- a/mkapi/core/renderer.py +++ b/mkapi/core/renderer.py @@ -105,7 +105,7 @@ def render_docstring(self, docstring: Docstring, filters: List[str] = None) -> s Args: docstring: Docstring instance. """ - if docstring is None: + if not docstring: return "" template = self.templates["docstring"] for section in docstring.sections: diff --git a/mkapi/core/structure.py b/mkapi/core/structure.py index 6482fa97..a6d5a1f2 100644 --- a/mkapi/core/structure.py +++ b/mkapi/core/structure.py @@ -115,7 +115,7 @@ def __repr__(self): return f"{class_name}({id!r}, num_sections={sections}, num_members={numbers})" def __getitem__(self, index: Union[int, str, List[str]]): - """Returns a member Tree instance. + """Returns a member {class} instance. If `index` is str, a member Tree instance whose name is equal to `index` is returned. diff --git a/tests/core/test_core_attribute.py b/tests/core/test_core_attribute.py index ec9469fa..efd293ce 100644 --- a/tests/core/test_core_attribute.py +++ b/tests/core/test_core_attribute.py @@ -132,5 +132,16 @@ def func(self): def test_multiple_assignments(): attrs = get_attributes(E) - assert attrs['a'] == (int, 'a') - assert attrs['b'] == (str, 'b') + assert attrs["a"] == (int, "a") + assert attrs["b"] == (str, "b") + + +def test_name_error(): + abc = "abc" + + class Name: + def __init__(self): + self.x: abc = 1 #: abc. + + attrs = get_attributes(Name) + assert attrs["x"] == ("abc", "abc.") diff --git a/tests/core/test_core_base.py b/tests/core/test_core_base.py index 27fe0896..e8e05a46 100644 --- a/tests/core/test_core_base.py +++ b/tests/core/test_core_base.py @@ -1,6 +1,6 @@ import pytest -from mkapi.core.base import Docstring, Item, Section +from mkapi.core.base import Base, Docstring, Item, Section def test_update_item(): @@ -38,3 +38,10 @@ def test_docstring_copy(): d.set_section(a, copy=True) assert "Arguments" in d assert d["Arguments"] is not a + + +def test_copy(): + x = Base("x", 'markdown') + y = x.copy() + assert y.name == 'x' + assert y.markdown == 'markdown' diff --git a/tests/core/test_core_inherit.py b/tests/core/test_core_inherit.py index 42736128..b6b728db 100644 --- a/tests/core/test_core_inherit.py +++ b/tests/core/test_core_inherit.py @@ -1,8 +1,24 @@ +from itertools import product + +import pytest + from mkapi.core.base import Base, Inline -from mkapi.core.inherit import is_complete +from mkapi.core.inherit import get_section, is_complete from mkapi.core.node import Node def test_is_complete(): assert is_complete(Node(Base)) assert not is_complete(Node(Inline)) + + +@pytest.mark.parametrize( + "name, mode", product(["Parameters", "Attributes"], ["Docstring", "Signature"]) +) +def test_get_section(name, mode): + def func(): + pass + + section = get_section(Node(func), name, mode) + section.name == name + assert not section diff --git a/tests/core/test_core_postprocess.py b/tests/core/test_core_postprocess.py index aad297e4..aa992ff0 100644 --- a/tests/core/test_core_postprocess.py +++ b/tests/core/test_core_postprocess.py @@ -51,11 +51,11 @@ def test_transform_property(node): def test_get_type(node): assert P.get_type(node).name == "" - assert P.get_type(node['f']).name == "str" - assert P.get_type(node['g']).name == "int" - assert P.get_type(node['a']).name == "(int, str)" - assert P.get_type(node['b']).name == "str" - node['g'].docstring.sections[1] + assert P.get_type(node["f"]).name == "str" + assert P.get_type(node["g"]).name == "int" + assert P.get_type(node["a"]).name == "(int, str)" + assert P.get_type(node["b"]).name == "str" + node["g"].docstring.sections[1] def test_transform_class(node): @@ -97,6 +97,6 @@ def test_link_from_toc(): P.transform(node) assert len(node.docstring.sections) == 5 assert "Methods" in node.docstring - section = node.docstring['Methods'] + section = node.docstring["Methods"] html = section.items[0].html assert '' in html diff --git a/tests/core/test_core_preprocess.py b/tests/core/test_core_preprocess.py index 2bc5d019..338445ef 100644 --- a/tests/core/test_core_preprocess.py +++ b/tests/core/test_core_preprocess.py @@ -1,4 +1,4 @@ -from mkapi.core.preprocess import convert +from mkapi.core.preprocess import admonition, convert source = """ABC @@ -32,3 +32,12 @@ def test_convert(): assert convert(source) == output + + +def test_admonition(): + markdown = admonition("Warnings", "abc\n\ndef") + assert markdown == '!!! warning "Warnings"\n abc\n\n def' + markdown = admonition("Note", "abc\n\ndef") + assert markdown == '!!! note "Note"\n abc\n\n def' + markdown = admonition("Tips", "abc\n\ndef") + assert markdown == '!!! tips "Tips"\n abc\n\n def' diff --git a/tests/core/test_core_renderer.py b/tests/core/test_core_renderer.py new file mode 100644 index 00000000..075eca48 --- /dev/null +++ b/tests/core/test_core_renderer.py @@ -0,0 +1,22 @@ +from mkapi.core.code import get_code +from mkapi.core.module import get_module +from mkapi.core.renderer import renderer + + +def test_module_empty_filters(): + module = get_module("mkapi.core.base") + m = renderer.render_module(module).split("\n") + assert m[0] == "# ![mkapi](mkapi.core.base|plain|link|sourcelink)" + assert m[2] == "## ![mkapi](mkapi.core.base.Base||link|sourcelink)" + assert m[3] == "## ![mkapi](mkapi.core.base.Inline||link|sourcelink)" + assert m[4] == "## ![mkapi](mkapi.core.base.Type||link|sourcelink)" + assert m[5] == "## ![mkapi](mkapi.core.base.Item||link|sourcelink)" + + +def test_code_empty_filters(): + code = get_code("mkapi.core.base") + m = renderer.render_code(code) + assert 'mkapi.core.' in m + assert 'base' in m + assert '' in m + assert 'DOCS' in m diff --git a/tests/plugins/test_plugins_mkdocs.py b/tests/plugins/test_plugins_mkdocs.py index d4a67c32..75591a4d 100644 --- a/tests/plugins/test_plugins_mkdocs.py +++ b/tests/plugins/test_plugins_mkdocs.py @@ -64,6 +64,6 @@ def test_plugins_mkdocs_build(): def run(command): assert subprocess.run(command.split()).returncode == 0 - if os.path.exists('docs/api'): - shutil.rmtree('docs/api') + if os.path.exists("docs/api"): + shutil.rmtree("docs/api") run("mkdocs build") diff --git a/tests/test_main.py b/tests/test_main.py deleted file mode 100644 index 23955ed3..00000000 --- a/tests/test_main.py +++ /dev/null @@ -1,2 +0,0 @@ -def test_main(): - assert 2