From 0cfb70212d219e8729b7fddb94f393f469665ecd Mon Sep 17 00:00:00 2001
From: Josh Morman <jmorman@gnuradio.org>
Date: Wed, 24 Nov 2021 12:50:06 -0500
Subject: docs: pep8 formatting
Signed-off-by: Josh Morman <jmorman@gnuradio.org>
---
docs/doxygen/update_pydoc.py | 118 +++++++++++++++++++++++++++----------------
1 file changed, 74 insertions(+), 44 deletions(-)
(limited to 'docs/doxygen/update_pydoc.py')
diff --git a/docs/doxygen/update_pydoc.py b/docs/doxygen/update_pydoc.py
index ccf982ac9b..b65e168ae5 100644
--- a/docs/doxygen/update_pydoc.py
+++ b/docs/doxygen/update_pydoc.py
@@ -16,16 +16,23 @@ python docstrings.
"""
-import os, sys, time, glob, re, json
+import os
+import sys
+import time
+import glob
+import re
+import json
from argparse import ArgumentParser
from doxyxml import DoxyIndex, DoxyClass, DoxyFriend, DoxyFunction, DoxyFile
from doxyxml import DoxyOther, base
+
def py_name(name):
bits = name.split('_')
return '_'.join(bits[1:])
+
def make_name(name):
bits = name.split('_')
return bits[0] + '_make_' + '_'.join(bits[1:])
@@ -50,6 +57,7 @@ class Block(object):
is_a_block = di.has_member(friendname, DoxyFunction)
return is_a_block
+
class Block2(object):
"""
Checks if doxyxml produced objects correspond to a new style
@@ -63,7 +71,8 @@ class Block2(object):
# Check for a parsing error.
if item.error():
return False
- is_a_block2 = item.has_member('make', DoxyFunction) and item.has_member('sptr', DoxyOther)
+ is_a_block2 = item.has_member(
+ 'make', DoxyFunction) and item.has_member('sptr', DoxyOther)
return is_a_block2
@@ -94,6 +103,7 @@ def combine_descriptions(obj):
description.append(dd)
return utoascii('\n\n'.join(description)).strip()
+
def format_params(parameteritems):
output = ['Args:']
template = ' {0} : {1}'
@@ -101,7 +111,10 @@ def format_params(parameteritems):
output.append(template.format(pi.name, pi.description))
return '\n'.join(output)
+
entry_templ = '%feature("docstring") {name} "{docstring}"'
+
+
def make_entry(obj, name=None, templ="{description}", description=None, params=[]):
"""
Create a docstring key/value pair, where the key is the object name.
@@ -114,9 +127,9 @@ def make_entry(obj, name=None, templ="{description}", description=None, params=[
used as the description instead of extracting it from obj.
"""
if name is None:
- name=obj.name()
- if hasattr(obj,'_parse_data') and hasattr(obj._parse_data,'definition'):
- name=obj._parse_data.definition.split(' ')[-1]
+ name = obj.name()
+ if hasattr(obj, '_parse_data') and hasattr(obj._parse_data, 'definition'):
+ name = obj._parse_data.definition.split(' ')[-1]
if "operator " in name:
return ''
if description is None:
@@ -174,9 +187,10 @@ def make_block_entry(di, block):
output = {}
output.update(make_class_entry(block, description=super_description))
output.update(make_entry(make_func, description=super_description,
- params=block.params))
+ params=block.params))
return output
+
def make_block2_entry(di, block):
"""
Create class and function docstrings of a new style gnuradio block
@@ -186,19 +200,21 @@ def make_block2_entry(di, block):
class_description = combine_descriptions(block)
make_func = block.get_member('make', DoxyFunction)
make_description = combine_descriptions(make_func)
- description = class_description + "\n\nConstructor Specific Documentation:\n\n" + make_description
+ description = class_description + \
+ "\n\nConstructor Specific Documentation:\n\n" + make_description
# Associate the combined description with the class and
# the make function.
output = {}
output.update(make_class_entry(
- block, description=description,
- ignored_methods=['make'], params=make_func.params))
+ block, description=description,
+ ignored_methods=['make'], params=make_func.params))
makename = block.name() + '::make'
output.update(make_entry(
- make_func, name=makename, description=description,
- params=make_func.params))
+ make_func, name=makename, description=description,
+ params=make_func.params))
return output
+
def get_docstrings_dict(di, custom_output=None):
output = {}
@@ -218,19 +234,21 @@ def get_docstrings_dict(di, custom_output=None):
make_funcs.add(make_func.name())
output.update(make_block_entry(di, block))
except block.ParsingError:
- sys.stderr.write('Parsing error for block {0}\n'.format(block.name()))
+ sys.stderr.write(
+ 'Parsing error for block {0}\n'.format(block.name()))
raise
for block in blocks2:
try:
make_func = block.get_member('make', DoxyFunction)
- make_func_name = block.name() +'::make'
+ make_func_name = block.name() + '::make'
# Don't want to risk writing to output twice.
if make_func_name not in make_funcs:
make_funcs.add(make_func_name)
output.update(make_block2_entry(di, block))
except block.ParsingError:
- sys.stderr.write('Parsing error for block {0}\n'.format(block.name()))
+ sys.stderr.write(
+ 'Parsing error for block {0}\n'.format(block.name()))
raise
# Create docstrings for functions
@@ -241,7 +259,8 @@ def get_docstrings_dict(di, custom_output=None):
try:
output.update(make_entry(f))
except f.ParsingError:
- sys.stderr.write('Parsing error for function {0}\n'.format(f.name()))
+ sys.stderr.write(
+ 'Parsing error for function {0}\n'.format(f.name()))
# Create docstrings for classes
block_names = [block.name() for block in blocks]
@@ -259,60 +278,69 @@ def get_docstrings_dict(di, custom_output=None):
return output
+
def sub_docstring_in_pydoc_h(pydoc_files, docstrings_dict, output_dir, filter_str=None):
if filter_str:
- docstrings_dict = {k: v for k, v in docstrings_dict.items() if k.startswith(filter_str)}
+ docstrings_dict = {
+ k: v for k, v in docstrings_dict.items() if k.startswith(filter_str)}
+
+ with open(os.path.join(output_dir, 'docstring_status'), 'w') as status_file:
- with open(os.path.join(output_dir,'docstring_status'),'w') as status_file:
-
for pydoc_file in pydoc_files:
if filter_str:
- filter_str2 = "::".join((filter_str,os.path.split(pydoc_file)[-1].split('_pydoc_template.h')[0]))
- docstrings_dict2 = {k: v for k, v in docstrings_dict.items() if k.startswith(filter_str2)}
+ filter_str2 = "::".join((filter_str, os.path.split(
+ pydoc_file)[-1].split('_pydoc_template.h')[0]))
+ docstrings_dict2 = {
+ k: v for k, v in docstrings_dict.items() if k.startswith(filter_str2)}
else:
docstrings_dict2 = docstrings_dict
-
-
- file_in = open(pydoc_file,'r').read()
- for key, value in docstrings_dict2.items():
- file_in_tmp = file_in
+ file_in = open(pydoc_file, 'r').read()
+ for key, value in docstrings_dict2.items():
+ file_in_tmp = file_in
try:
doc_key = key.split("::")
# if 'gr' in doc_key:
- # doc_key.remove('gr')
+ # doc_key.remove('gr')
doc_key = '_'.join(doc_key)
- regexp = r'(__doc_{} =\sR\"doc\()[^)]*(\)doc\")'.format(doc_key)
+ regexp = r'(__doc_{} =\sR\"doc\()[^)]*(\)doc\")'.format(
+ doc_key)
regexp = re.compile(regexp, re.MULTILINE)
-
- (file_in, nsubs) = regexp.subn(r'\1'+value+r'\2', file_in, count=1)
+
+ (file_in, nsubs) = regexp.subn(
+ r'\1' + value + r'\2', file_in, count=1)
if nsubs == 1:
status_file.write("PASS: " + pydoc_file + "\n")
except KeyboardInterrupt:
raise KeyboardInterrupt
- except: # be permissive, TODO log, but just leave the docstring blank
+ except: # be permissive, TODO log, but just leave the docstring blank
status_file.write("FAIL: " + pydoc_file + "\n")
file_in = file_in_tmp
- output_pathname = os.path.join(output_dir, os.path.basename(pydoc_file).replace('_template.h','.h'))
- with open(output_pathname,'w') as file_out:
+ output_pathname = os.path.join(output_dir, os.path.basename(
+ pydoc_file).replace('_template.h', '.h'))
+ with open(output_pathname, 'w') as file_out:
file_out.write(file_in)
+
def copy_docstring_templates(pydoc_files, output_dir):
- with open(os.path.join(output_dir,'docstring_status'),'w') as status_file:
+ with open(os.path.join(output_dir, 'docstring_status'), 'w') as status_file:
for pydoc_file in pydoc_files:
- file_in = open(pydoc_file,'r').read()
- output_pathname = os.path.join(output_dir, os.path.basename(pydoc_file).replace('_template.h','.h'))
- with open(output_pathname,'w') as file_out:
+ file_in = open(pydoc_file, 'r').read()
+ output_pathname = os.path.join(output_dir, os.path.basename(
+ pydoc_file).replace('_template.h', '.h'))
+ with open(output_pathname, 'w') as file_out:
file_out.write(file_in)
status_file.write("DONE")
+
def argParse():
"""Parses commandline args."""
- desc='Scrape the doxygen generated xml for docstrings to insert into python bindings'
+ desc = 'Scrape the doxygen generated xml for docstrings to insert into python bindings'
parser = ArgumentParser(description=desc)
-
- parser.add_argument("function", help="Operation to perform on docstrings", choices=["scrape","sub","copy"])
+
+ parser.add_argument("function", help="Operation to perform on docstrings", choices=[
+ "scrape", "sub", "copy"])
parser.add_argument("--xml_path")
parser.add_argument("--bindings_dir")
@@ -322,6 +350,7 @@ def argParse():
return parser.parse_args()
+
if __name__ == "__main__":
# Parse command line options and set up doxyxml.
args = argParse()
@@ -333,10 +362,11 @@ if __name__ == "__main__":
elif args.function.lower() == 'sub':
with open(args.json_path, 'r') as fp:
docstrings_dict = json.load(fp)
- pydoc_files = glob.glob(os.path.join(args.bindings_dir,'*_pydoc_template.h'))
- sub_docstring_in_pydoc_h(pydoc_files, docstrings_dict, args.output_dir, args.filter)
+ pydoc_files = glob.glob(os.path.join(
+ args.bindings_dir, '*_pydoc_template.h'))
+ sub_docstring_in_pydoc_h(
+ pydoc_files, docstrings_dict, args.output_dir, args.filter)
elif args.function.lower() == 'copy':
- pydoc_files = glob.glob(os.path.join(args.bindings_dir,'*_pydoc_template.h'))
+ pydoc_files = glob.glob(os.path.join(
+ args.bindings_dir, '*_pydoc_template.h'))
copy_docstring_templates(pydoc_files, args.output_dir)
-
-
--
cgit v1.2.3