def assert_code_as_markdown(source_code,
markdown,
full=False,
parser_options=None):
config = PydocMarkdown()
# Init the settings in which we want to run the tests.
config.renderer.insert_header_anchors = False
config.renderer.add_member_class_prefix = False
config.renderer.render_toc = False
config.renderer.render_module_header = full
filter_processor = next(x for x in config.processors
if isinstance(x, FilterProcessor))
filter_processor.documented_only = False
# Load the source code as a module.
modules = [
parse_python_module(
io.StringIO(textwrap.dedent(source_code)),
filename='<string>',
module_name='_inline',
options=parser_options,
)
]
config.process(modules)
result = config.renderer.render_to_string(modules)
assert_text_equals(result, textwrap.dedent(markdown))
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 generate_pydoc(
module: str,
article_id: str,
article_title: str,
target_dir: str,
module_overview: str,
func_prefix: Optional[str] = None,
) -> 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.processors[0] = IgnoreDocstringProcessor()
pydocmd.processors[1] = SmartProcessor(
sphinx=CommonServerPythonProcessor())
pydocmd.renderer = DemistoMarkdownRenderer(
insert_header_anchors=False,
func_prefix=func_prefix,
module_overview=module_overview,
escape_html_in_docstring=True,
classdef_code_block=False,
descriptive_class_title=False,
signature_with_decorators=False,
signature_class_prefix=True,
)
loader: PythonLoader = next(
(ldr for ldr in pydocmd.loaders if isinstance(ldr, PythonLoader)),
None)
loader.modules = [module]
modules = pydocmd.load_modules()
pydocmd.process(modules)
pydoc = pydocmd.renderer.render_to_string(modules)
article_description = f'API reference documentation for {article_title}.'
content = f'---\nid: {article_id}\ntitle: {article_title}\ndescription: {article_description}\n---\n\n{module_overview}\n\n{pydoc}'
with open(f'{target_dir}/{article_id}.md', mode='w',
encoding='utf-8') as f:
f.write(content)
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 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 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)
def load(self) -> PydocMarkdown:
"""
Loads the configuration and applies the overrides.
"""
config = PydocMarkdown()
if self.config:
config.load_config(self.config)
self._apply_overrides(config)
if isinstance(self.config, str):
config.init(Context(directory=os.path.dirname(os.path.abspath(self.config))))
if config.unknown_fields:
logger.warning('Unknown configuration options: %s', ', '.join(config.unknown_fields))
return config
def build(self, config: PydocMarkdown, site_dir: str) -> None:
config.build(site_dir)
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
""")
