def py2md(module: str, out: Optional[str] = None) -> bool:
"""
Returns `True` if module successfully processed, otherwise `False`.
"""
logger.debug("Processing %s", module)
pydocmd = PydocMarkdown(
loaders=[PythonLoader(modules=[module])],
processors=[AllenNlpFilterProcessor(),
AllenNlpDocstringProcessor()],
renderer=AllenNlpRenderer(
filename=out,
add_method_class_prefix=False,
add_member_class_prefix=False,
data_code_block=True,
signature_with_def=True,
use_fixed_header_levels=False,
render_module_header=False,
descriptive_class_title=False,
),
)
if out:
out_path = Path(out)
os.makedirs(out_path.parent, exist_ok=True)
pydocmd.load_modules()
try:
pydocmd.process()
except DocstringError as err:
logger.exception("Failed to process %s.\n%s", module, err)
return False
pydocmd.render()
return True
def render(self, config: PydocMarkdown) -> List[str]:
"""
Kicks off the rendering process and returns a list of files to watch.
"""
modules = config.load_modules()
config.process(modules)
config.render(modules)
watch_files = set(m.location.filename for m in modules)
if isinstance(self.config, str):
watch_files.add(self.config)
return list(watch_files)
def test_full_processing_custom_top_level_names():
docs_path = Path(__file__).parent / "test_package" / "docs"
config = PydocMarkdown(
loaders=[
PythonLoader(search_path=[str(Path(__file__).parent.resolve())],
packages=['test_package'])
],
processors=[
FilterProcessor(skip_empty_modules=True),
CrossrefProcessor(),
SmartProcessor()
],
renderer=DocusaurusRenderer(
docs_base_path=str(docs_path.resolve()),
sidebar_top_level_label=None,
sidebar_top_level_module_label="My test package"))
modules = config.load_modules()
config.process(modules)
config.render(modules)
sidebar = docs_path / "reference" / "sidebar.json"
assert sidebar.exists()
with sidebar.open("r") as handle:
sidebar = json.load(handle)
assert sidebar == {
"items": [{
"items": [
"reference/test_package/module/__init__",
"reference/test_package/module/stuff"
],
"label":
"test_package.module",
"type":
"category"
}],
"label":
"My test package",
"type":
"category"
}
def py2md(module: str, out: Optional[str] = None) -> None:
pydocmd = PydocMarkdown(
loaders=[PythonLoader(modules=[module])],
processors=[AllenNlpFilterProcessor(), AllenNlpDocstringProcessor()],
renderer=AllenNlpRenderer(
filename=out,
add_method_class_prefix=False,
add_member_class_prefix=False,
data_code_block=True,
signature_with_def=True,
use_fixed_header_levels=False,
render_module_header=False,
),
)
if out:
out_path = Path(out)
os.makedirs(out_path.parent, exist_ok=True)
pydocmd.load_modules()
pydocmd.process()
pydocmd.render()
logging.info("Processed %s", module)
def generate_pydoc(module: str, article_id: str, article_title: str,
target_dir: str, func_prefix: Optional[str],
module_overview: Optional[str]) -> None:
"""
Args:
module (str): The Python module to parse and generate docs for.
article_id (str): The article ID.
article_title (str): The article title.
target_dir (str): The target directory to generate docs at.
func_prefix (str): Prefix to add to function signature.
module_overview (str): Module overview to add to the doc header.
Returns:
None: No data returned.
"""
pydocmd = PydocMarkdown()
pydocmd.renderer = DemistoMarkdownRenderer(insert_header_anchors=False,
func_prefix=func_prefix,
module_overview=module_overview)
loader: PythonLoader = next(
(ldr for ldr in pydocmd.loaders if isinstance(ldr, PythonLoader)),
None)
loader.modules = [module]
modules = pydocmd.load_modules()
pydocmd.process(modules)
stdout = sys.stdout
sys.stdout = tmp_stdout = StringIO()
pydocmd.render(modules)
sys.stdout = stdout
pydoc = tmp_stdout.getvalue()
article_description = f'API reference documentation for {article_title}.'
content = f'---\nid: {article_id}\ntitle: {article_title}\ndescription: {article_description}\n---\n\n{pydoc}'
with open(f'{target_dir}/{article_id}.md', mode='w',
encoding='utf-8') as f:
f.write(content)
import yaml
import os
import yaml
from pydoc_markdown import PydocMarkdown
if __name__ == "__main__":
config = yaml.safe_load(open(".pydocs"))
pydoc = PydocMarkdown()
pydoc.load_config(config)
pydoc.load_modules()
pydoc.process()
pydoc.render()
os.remove("build/docs/mkdocs.yml")
def test_full_processing():
docs_path = Path(__file__).parent / "test_package" / "docs"
config = PydocMarkdown(loaders=[
PythonLoader(search_path=[str(Path(__file__).parent.resolve())],
packages=['test_package'])
],
processors=[
FilterProcessor(skip_empty_modules=True),
CrossrefProcessor(),
SmartProcessor()
],
renderer=DocusaurusRenderer(
docs_base_path=str(docs_path.resolve()),
sidebar_top_level_label="Code reference"))
modules = config.load_modules()
config.process(modules)
config.render(modules)
sidebar = docs_path / "reference" / "sidebar.json"
init_md = docs_path / "reference" / "test_package" / "module" / "__init__.md"
wrong_module_init_md = docs_path / "reference" / "test_package" / "module.md"
suff_md = docs_path / "reference" / "test_package" / "module" / "stuff.md"
assert (docs_path / "reference").is_dir()
assert sidebar.exists()
assert suff_md.exists()
assert init_md.exists()
assert not wrong_module_init_md.exists()
assert not (docs_path / "reference" / "test_package" /
"no_docstrings.md").exists()
with sidebar.open("r") as handle:
sidebar = json.load(handle)
assert sidebar == {
"items": [{
"items": [{
"items": [
"reference/test_package/module/__init__",
"reference/test_package/module/stuff"
],
"label":
"test_package.module",
"type":
"category"
}],
"label":
"test_package",
"type":
"category"
}],
"label":
"Code reference",
"type":
"category"
}
with suff_md.open("r") as handle:
stuff_doc = handle.read()
assert_text_equals(
stuff_doc, r"""---
sidebar_label: stuff
title: test_package.module.stuff
---
This is a module about stuff.
#### CONSTANT
this is a constant about stuff
#### my\_funct
```python
my_funct()
```
Do something, or nothing.
## CoolStuff Objects
```python
class CoolStuff()
```
Super cool stuff.
#### cool\_attr
This is a cool attribute.
#### run\_cool\_stuff
```python
| run_cool_stuff()
```
Run cool stuff
""")
with init_md.open("r") as handle:
init_doc = handle.read()
assert_text_equals(
init_doc, r"""---
sidebar_label: module
title: test_package.module
---
This is module __init__.py
#### CONSTANT
This constant is rad
""")