Add support for ignoring objects via docstring

Author: lukasmasuch

src/lazydocs/generation.py

@@ -24,6 +24,8 @@
 _RE_TYPED_ARGSTART = re.compile(r"([\w\[\]_]{1,}?)\s*?\((.*?)\):(.{2,})", re.IGNORECASE)
 _RE_ARGSTART = re.compile(r"(.{1,}?):(.{2,})", re.IGNORECASE)
 
+_IGNORE_GENERATION_INSTRUCTION = "lazydocs: ignore"
+
 # String templates
 
 _SOURCE_BADGE_TEMPLATE = """
@@ -179,7 +181,7 @@ def _order_by_line_nos(objs: Any, line_nos: List[int]) -> List[str]:
 
 
 def to_md_file(
- string: str,
+ markdown_str: str,
  filename: str,
  out_path: str = ".",
  watermark: bool = True,
@@ -188,27 +190,31 @@ def to_md_file(
  """Creates an API docs file from a provided text.
 
  Args:
- string (str): String with line breaks to write to file.
+ markdown_str (str): Markdown string with line breaks to write to file.
  filename (str): Filename without the .md
  watermark (bool): If `True`, add a watermark with a timestamp to bottom of the markdown files.
  disable_markdownlint (bool): If `True`, an inline tag is added to disable markdownlint for this file.
  out_path (str): The output directory
  """
+ if not markdown_str:
+ # Dont write empty files
+ return
+
  md_file = filename
  if not filename.endswith(".md"):
  md_file = filename + ".md"
 
  if disable_markdownlint:
- string = "<!-- markdownlint-disable -->\n" + string
+ markdown_str = "<!-- markdownlint-disable -->\n" + markdown_str
 
  if watermark:
- string += _WATERMARK_TEMPLATE.format(
+ markdown_str += _WATERMARK_TEMPLATE.format(
  date=datetime.date.today().strftime("%d %b %Y")
  )
 
  print("Writing {}.".format(md_file))
  with open(os.path.join(out_path, md_file), "w") as f:
- f.write(string)
+ f.write(markdown_str)
 
 
 def _code_snippet(snippet: str) -> str:
@@ -254,6 +260,20 @@ def _get_class_that_defined_method(meth: Any) -> Any:
  return getattr(meth, "__objclass__", None) # handle special descriptor objects
 
 
+def _get_docstring(obj: Any) -> str:
+ return "" if obj.__doc__ is None else inspect.getdoc(obj) or ""
+
+
+def _is_object_ignored(obj: Any) -> bool:
+ if (
+ _IGNORE_GENERATION_INSTRUCTION.replace(" ", "").lower()
+ in _get_docstring(obj).replace(" ", "").lower()
+ ):
+ # Do not generate anything if docstring contains ignore instruction
+ return True
+ return False
+
+
 def _get_src_root_path(obj: Any) -> str:
  """Get the root path to a imported module.
 
@@ -271,9 +291,8 @@ def _get_src_root_path(obj: Any) -> str:
 
 
 def _get_doc_summary(obj: Any) -> str:
- doc = "" if obj.__doc__ is None else inspect.getdoc(obj) or ""
  # First line should contain the summary
- return doc.split("\n")[0]
+ return _get_docstring(obj).split("\n")[0]
 
 
 def _get_anchor_tag(header: str) -> str:
@@ -299,7 +318,7 @@ def _doc2md(obj: Any) -> str:
  # the documentation strings are now inherited if not overridden.
  # For details see: https://docs.python.org/3.6/library/inspect.html#inspect.getdoc
  # doc = getdoc(func) or ""
- doc = "" if obj.__doc__ is None else inspect.getdoc(obj) or ""
+ doc = _get_docstring(obj)
 
  blockindent = 0
  argindent = 1
@@ -480,6 +499,10 @@ def func2md(self, func: Callable, clsname: str = "", depth: int = 3) -> str:
  Returns:
  str: Markdown documentation for selected function.
  """
+ if _is_object_ignored(func):
+ # The function is ignored from generation
+ return ""
+
  section = "#" * depth
  funcname = func.__name__
  modname = None
@@ -560,6 +583,10 @@ def class2md(self, cls: Any, depth: int = 2) -> str:
  Returns:
  str: Markdown documentation for selected class.
  """
+ if _is_object_ignored(cls):
+ # The class is ignored from generation
+ return ""
+
  section = "#" * depth
  subsection = "#" * (depth + 2)
  clsname = cls.__name__
@@ -638,9 +665,9 @@ def class2md(self, cls: Any, depth: int = 2) -> str:
  # object module should be the same as the calling module
  and obj.__module__ == modname
  ):
- methods.append(
-  _SEPARATOR + self.func2md(obj, clsname=clsname, depth=depth + 1)
- )
+ function_md = self.func2md(obj, clsname=clsname, depth=depth + 1)
+ if function_md:
+  methods.append(_SEPARATOR + function_md)
 
  markdown = _CLASS_TEMPLATE.format(
  section=section,
@@ -667,6 +694,10 @@ def module2md(self, module: types.ModuleType, depth: int = 1) -> str:
  Returns:
  str: Markdown documentation for selected module.
  """
+ if _is_object_ignored(module):
+ # The module is ignored from generation
+ return ""
+
  modname = module.__name__
  doc = _doc2md(module)
  summary = _get_doc_summary(module)
@@ -694,8 +725,10 @@ def module2md(self, module: types.ModuleType, depth: int = 1) -> str:
  and hasattr(obj, "__module__")
  and obj.__module__ == modname
  ):
- classes.append(_SEPARATOR + self.class2md(obj, depth=depth + 1))
- line_nos.append(_get_line_no(obj) or 0)
+ class_markdown = self.class2md(obj, depth=depth + 1)
+ if class_markdown:
+ classes.append(_SEPARATOR + class_markdown)
+ line_nos.append(_get_line_no(obj) or 0)
  classes = _order_by_line_nos(classes, line_nos)
 
  functions: List[str] = []
@@ -708,8 +741,10 @@ def module2md(self, module: types.ModuleType, depth: int = 1) -> str:
  and hasattr(obj, "__module__")
  and obj.__module__ == modname
  ):
- functions.append(_SEPARATOR + self.func2md(obj, depth=depth + 1))
- line_nos.append(_get_line_no(obj) or 0)
+ function_md = self.func2md(obj, depth=depth + 1)
+ if function_md:
+ functions.append(_SEPARATOR + function_md)
+ line_nos.append(_get_line_no(obj) or 0)
  functions = _order_by_line_nos(functions, line_nos)
 
  variables: List[str] = []
@@ -894,7 +929,7 @@ def generate_docs(
  continue
 
  try:
- mod = loader.find_module(module_name).load_module(module_name)
+ mod = loader.find_module(module_name).load_module(module_name) # type: ignore
  module_md = generator.module2md(mod)
  if stdout_mode:
  print(module_md)
@@ -963,7 +998,7 @@ def generate_docs(
  if module_name.split(".")[-1].startswith("_"):
  continue
  try:
- mod = loader.find_module(module_name).load_module(
+ mod = loader.find_module(module_name).load_module( # type: ignore
  module_name
  )
  module_md = generator.module2md(mod)