mktestdocs 0.2.3__tar.gz → 0.2.5__tar.gz

mktestdocs-0.2.5/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mktestdocs
+Version: 0.2.5
+Summary: A tool for testing markdown documentation
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+<img src="icon.png" width=125 height=125 align="right">
+
+### mktestdocs
+
+Run pytest against markdown files/docstrings.
+
+# Installation 
+
+```
+pip install mktestdocs
+```
+
+## Usage 
+
+Let's say that you're using [mkdocs](https://squidfunk.github.io/mkdocs-material/getting-started/) 
+for your documentation. Then you're writing down markdown to explain how your Python packages work. 
+It'd be a shame if a codeblock had an error in it, so it'd be 
+great if you could run your unit tests against them. 
+
+This package allows you to do _just that_. Here's an example:
+
+```python
+import pathlib
+import pytest
+
+from mktestdocs import check_md_file
+
+# Note the use of `str`, makes for pretty output
+@pytest.mark.parametrize('fpath', pathlib.Path("docs").glob("**/*.md"), ids=str)
+def test_files_good(fpath):
+    check_md_file(fpath=fpath)
+```
+
+This will take any codeblock that starts with *\`\`\`python* and run it, checking
+for any errors that might happen. This means that if your docs contain asserts, that
+you get some unit-tests for free! 
+
+## Multiple Code Blocks 
+
+Let's suppose that you have the following markdown file: 
+
+    This is a code block
+
+    ```python
+    from operator import add
+    a = 1
+    b = 2
+    ```
+
+    This code-block should run fine.
+
+    ```python
+    assert add(1, 2) == 3
+    ```
+
+Then in this case the second code-block depends on the first code-block. The standard settings of `check_md_file` assume that each code-block needs to run independently. If you'd like to test markdown files with these sequential code-blocks be sure to set `memory=True`. 
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "multiple-code-blocks.md"
+
+try:
+    # Assume that cell-blocks are independent.
+    check_md_file(fpath=fpath)
+except NameError:
+    # But they weren't
+    pass
+
+# Assumes that cell-blocks depend on each other.
+check_md_file(fpath=fpath, memory=True)
+```
+
+## Markdown in Docstrings
+
+You might also have docstrings written in markdown. Those can be easily checked
+as well. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import roar, super_roar
+
+import pytest
+from mktestdocs import check_docstring
+
+# Note the use of `__name__`, makes for pretty output
+@pytest.mark.parametrize('func', [roar, super_roar], ids=lambda d: d.__name__)
+def test_docstring(func):
+    check_docstring(obj=func)
+```
+
+There's even some utilities for grab all the docstrings from classes that you've defined. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import Dinosaur
+
+import pytest
+from mktestdocs import check_docstring, get_codeblock_members
+
+# This retrieves all methods/properties that have a docstring.
+members = get_codeblock_members(Dinosaur)
+
+# Note the use of `__qualname__`, makes for pretty output
+@pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)
+def test_member(obj):
+    check_docstring(obj)
+```
+
+When you run these commands via `pytest --verbose` you should see informative test info being run. 
+
+If you're wondering why you'd want to write markdown in a docstring feel free to check out [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings).
+
+## Bash Support
+
+Be default, bash code blocks are also supported. A markdown file that contains
+both python and bash code blocks can have each executed separately.
+
+    This will print the python version to the terminal
+
+    ```bash
+    python --version
+    ```
+
+    This will print the exact same version string
+
+    ```python
+    import sys
+
+    print(f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    ```
+
+This markdown could be fully tested like this
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "bash-support.md"
+
+check_md_file(fpath=fpath, lang="python")
+check_md_file(fpath=fpath, lang="bash")
+```
+
+## Additional Language Support
+
+You can add support for languages other than python and bash by first
+registering a new executor for that language. The `register_executor` function
+takes a tag to specify the code block type supported, and a function that will
+be passed any code blocks found in markdown files.
+
+For example if you have a markdown file like this
+
+````markdown
+This is an example REST response
+
+```json
+{"body": {"results": ["spam", "eggs"]}, "errors": []}
+```
+````
+
+You could create a json validator that tested the example was always valid json like this
+
+```python
+import json
+import pathlib
+
+from mktestdocs import check_md_file, register_executor
+
+def parse_json(json_text):
+    json.loads(json_text)
+
+register_executor("json", parse_json)
+
+check_md_file(fpath=pathlib.Path("docs") / "additional-language-support.md", lang="json")
+```

mktestdocs-0.2.5/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mktestdocs"
+version = "0.2.5"
+description = "A tool for testing markdown documentation"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+dependencies = []
+
+[project.optional-dependencies]
+test = ["pytest"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

{mktestdocs-0.2.3 → mktestdocs-0.2.5/src}/mktestdocs/__init__.py

@@ -1,4 +1,5 @@
-from mktestdocs.__main__ import (
+import importlib.metadata
+from .__main__ import (
     register_executor,
     check_codeblock,
     grab_code_blocks,
@@ -7,7 +8,7 @@ from mktestdocs.__main__ import (
     get_codeblock_members,
 )
 
-__version__ = "0.2.3"
+__version__ = importlib.metadata.version("mktestdocs")
 
 __all__ = [
     "__version__",

{mktestdocs-0.2.3 → mktestdocs-0.2.5/src}/mktestdocs/__main__.py

@@ -40,7 +40,7 @@ def exec_python(source):
     will propagate out unmodified
     """
     try:
-        exec(source, {"__MODULE__": "__main__"})
+        exec(source, {"__name__": "__main__"})
     except Exception:
         print(source)
         raise
@@ -50,7 +50,7 @@ register_executor("", exec_python)
 register_executor("python", exec_python)
 
 
-def get_codeblock_members(*classes):
+def get_codeblock_members(*classes, lang="python"):
     """
     Grabs the docstrings of any methods of any classes that are passed in.
     """
@@ -61,7 +61,7 @@ def get_codeblock_members(*classes):
         for name, member in inspect.getmembers(cl):
             if member.__doc__:
                 results.append(member)
-    return [m for m in results if len(grab_code_blocks(m.__doc__)) > 0]
+    return [m for m in results if len(grab_code_blocks(m.__doc__, lang=lang)) > 0]
 
 
 def check_codeblock(block, lang="python"):
@@ -76,7 +76,7 @@ def check_codeblock(block, lang="python"):
     """
     first_line = block.split("\n")[0]
     if lang:
-        if first_line[3:] != lang:
+        if first_line.lstrip()[3:] != lang:
             return ""
     return "\n".join(block.split("\n")[1:])
 
@@ -104,12 +104,14 @@ def grab_code_blocks(docstring, lang="python"):
             block += line + "\n"
     return [textwrap.dedent(c) for c in codeblocks if c != ""]
 
+
 def format_docstring(docstring):
     """Formats docstring to be able to successfully go through dedent."""
     if docstring[:1] != "\n":
         return f"\n    {docstring}"
     return docstring
 
+
 def check_docstring(obj, lang=""):
     """
     Given a function, test the contents of the docstring.

mktestdocs-0.2.5/src/mktestdocs.egg-info/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: mktestdocs
+Version: 0.2.5
+Summary: A tool for testing markdown documentation
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+<img src="icon.png" width=125 height=125 align="right">
+
+### mktestdocs
+
+Run pytest against markdown files/docstrings.
+
+# Installation 
+
+```
+pip install mktestdocs
+```
+
+## Usage 
+
+Let's say that you're using [mkdocs](https://squidfunk.github.io/mkdocs-material/getting-started/) 
+for your documentation. Then you're writing down markdown to explain how your Python packages work. 
+It'd be a shame if a codeblock had an error in it, so it'd be 
+great if you could run your unit tests against them. 
+
+This package allows you to do _just that_. Here's an example:
+
+```python
+import pathlib
+import pytest
+
+from mktestdocs import check_md_file
+
+# Note the use of `str`, makes for pretty output
+@pytest.mark.parametrize('fpath', pathlib.Path("docs").glob("**/*.md"), ids=str)
+def test_files_good(fpath):
+    check_md_file(fpath=fpath)
+```
+
+This will take any codeblock that starts with *\`\`\`python* and run it, checking
+for any errors that might happen. This means that if your docs contain asserts, that
+you get some unit-tests for free! 
+
+## Multiple Code Blocks 
+
+Let's suppose that you have the following markdown file: 
+
+    This is a code block
+
+    ```python
+    from operator import add
+    a = 1
+    b = 2
+    ```
+
+    This code-block should run fine.
+
+    ```python
+    assert add(1, 2) == 3
+    ```
+
+Then in this case the second code-block depends on the first code-block. The standard settings of `check_md_file` assume that each code-block needs to run independently. If you'd like to test markdown files with these sequential code-blocks be sure to set `memory=True`. 
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "multiple-code-blocks.md"
+
+try:
+    # Assume that cell-blocks are independent.
+    check_md_file(fpath=fpath)
+except NameError:
+    # But they weren't
+    pass
+
+# Assumes that cell-blocks depend on each other.
+check_md_file(fpath=fpath, memory=True)
+```
+
+## Markdown in Docstrings
+
+You might also have docstrings written in markdown. Those can be easily checked
+as well. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import roar, super_roar
+
+import pytest
+from mktestdocs import check_docstring
+
+# Note the use of `__name__`, makes for pretty output
+@pytest.mark.parametrize('func', [roar, super_roar], ids=lambda d: d.__name__)
+def test_docstring(func):
+    check_docstring(obj=func)
+```
+
+There's even some utilities for grab all the docstrings from classes that you've defined. 
+
+```python
+# I'm assuming that we've got a library called dinosaur
+from dinosaur import Dinosaur
+
+import pytest
+from mktestdocs import check_docstring, get_codeblock_members
+
+# This retrieves all methods/properties that have a docstring.
+members = get_codeblock_members(Dinosaur)
+
+# Note the use of `__qualname__`, makes for pretty output
+@pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)
+def test_member(obj):
+    check_docstring(obj)
+```
+
+When you run these commands via `pytest --verbose` you should see informative test info being run. 
+
+If you're wondering why you'd want to write markdown in a docstring feel free to check out [mkdocstrings](https://github.com/mkdocstrings/mkdocstrings).
+
+## Bash Support
+
+Be default, bash code blocks are also supported. A markdown file that contains
+both python and bash code blocks can have each executed separately.
+
+    This will print the python version to the terminal
+
+    ```bash
+    python --version
+    ```
+
+    This will print the exact same version string
+
+    ```python
+    import sys
+
+    print(f"Python {sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")
+    ```
+
+This markdown could be fully tested like this
+
+```python
+import pathlib
+
+from mktestdocs import check_md_file
+
+fpath = pathlib.Path("docs") / "bash-support.md"
+
+check_md_file(fpath=fpath, lang="python")
+check_md_file(fpath=fpath, lang="bash")
+```
+
+## Additional Language Support
+
+You can add support for languages other than python and bash by first
+registering a new executor for that language. The `register_executor` function
+takes a tag to specify the code block type supported, and a function that will
+be passed any code blocks found in markdown files.
+
+For example if you have a markdown file like this
+
+````markdown
+This is an example REST response
+
+```json
+{"body": {"results": ["spam", "eggs"]}, "errors": []}
+```
+````
+
+You could create a json validator that tested the example was always valid json like this
+
+```python
+import json
+import pathlib
+
+from mktestdocs import check_md_file, register_executor
+
+def parse_json(json_text):
+    json.loads(json_text)
+
+register_executor("json", parse_json)
+
+check_md_file(fpath=pathlib.Path("docs") / "additional-language-support.md", lang="json")
+```

mktestdocs-0.2.5/src/mktestdocs.egg-info/SOURCES.txt

@@ -0,0 +1,16 @@
+LICENSE
+README.md
+pyproject.toml
+src/mktestdocs/__init__.py
+src/mktestdocs/__main__.py
+src/mktestdocs.egg-info/PKG-INFO
+src/mktestdocs.egg-info/SOURCES.txt
+src/mktestdocs.egg-info/dependency_links.txt
+src/mktestdocs.egg-info/requires.txt
+src/mktestdocs.egg-info/top_level.txt
+tests/test_actual_docstrings.py
+tests/test_class.py
+tests/test_codeblock.py
+tests/test_format_docstring.py
+tests/test_markdown.py
+tests/test_mktestdocs.py

mktestdocs-0.2.5/src/mktestdocs.egg-info/requires.txt

@@ -0,0 +1,3 @@
+
+[test]
+pytest

{mktestdocs-0.2.3 → mktestdocs-0.2.5}/tests/test_class.py

@@ -60,12 +60,27 @@ class Dinosaur:
         """
         return self.name
 
+    def hfdocs_style(self, value):
+        """
+        Returns value
+
+        Example:
+
+            ```python
+            from dinosaur import Dinosaur
+
+            dino = Dinosaur()
+            assert dino.a(1) == 1
+            ```
+        """
+        return value
+
 
 members = get_codeblock_members(Dinosaur)
 
 
 def test_grab_methods():
-    assert len(get_codeblock_members(Dinosaur)) == 4
+    assert len(get_codeblock_members(Dinosaur)) == 5
 
 
 @pytest.mark.parametrize("obj", members, ids=lambda d: d.__qualname__)

{mktestdocs-0.2.3 → mktestdocs-0.2.5}/tests/test_mktestdocs.py

@@ -2,9 +2,10 @@ import pathlib
 
 from mktestdocs import check_md_file
 
+
 def test_readme(monkeypatch):
     test_dir = pathlib.Path(__file__).parent
     fpath = test_dir.parent / "README.md"
     monkeypatch.chdir(test_dir)
 
-    check_md_file(fpath=fpath)
+    check_md_file(fpath=fpath, memory=True)

mktestdocs-0.2.3/PKG-INFO

@@ -1,6 +0,0 @@
-Metadata-Version: 2.1
-Name: mktestdocs
-Version: 0.2.3
-License-File: LICENSE
-Provides-Extra: test
-Requires-Dist: pytest>=4.0.2; extra == "test"

mktestdocs-0.2.3/mktestdocs.egg-info/PKG-INFO

@@ -1,6 +0,0 @@
-Metadata-Version: 2.1
-Name: mktestdocs
-Version: 0.2.3
-License-File: LICENSE
-Provides-Extra: test
-Requires-Dist: pytest>=4.0.2; extra == "test"

mktestdocs-0.2.3/mktestdocs.egg-info/SOURCES.txt

@@ -1,16 +0,0 @@
-LICENSE
-README.md
-setup.py
-mktestdocs/__init__.py
-mktestdocs/__main__.py
-mktestdocs.egg-info/PKG-INFO
-mktestdocs.egg-info/SOURCES.txt
-mktestdocs.egg-info/dependency_links.txt
-mktestdocs.egg-info/requires.txt
-mktestdocs.egg-info/top_level.txt
-tests/test_actual_docstrings.py
-tests/test_class.py
-tests/test_codeblock.py
-tests/test_format_docstring.py
-tests/test_markdown.py
-tests/test_mktestdocs.py

mktestdocs-0.2.3/mktestdocs.egg-info/requires.txt

@@ -1,3 +0,0 @@
-
-[test]
-pytest>=4.0.2

mktestdocs-0.2.3/setup.py

@@ -1,14 +0,0 @@
-from mktestdocs import __version__
-from setuptools import setup, find_packages
-
-test_packages = ["pytest>=4.0.2"]
-
-setup(
-    name="mktestdocs",
-    version=__version__,
-    packages=find_packages(exclude=["tests"]),
-    install_requires=[],
-    extras_require={
-        "test": test_packages,
-    },
-)