Skip to content

Commit a275e37

Browse files
Chnage API reference generator to hide package names in class headers.
1 parent 1e09e05 commit a275e37

File tree

1 file changed

+16
-34
lines changed

1 file changed

+16
-34
lines changed

tools/db_object_doc_gen.py

Lines changed: 16 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -71,11 +71,6 @@ def tag(text, tag, values={}):
7171
return "<%s%s>%s</%s>" % (tag, values, text, tag)
7272

7373

74-
def qual_class_name(cls):
75-
""" Returns the fully qualifieid class name (module + class name). """
76-
return cls.__module__ + "." + cls.__name__
77-
78-
7974
def header(level, text, header_id=None):
8075
""" Wraps `text` into a <h> (header) tag ov the given level.
8176
Automatically increases the level by 2 to be inline with HelpDocs
@@ -98,8 +93,10 @@ def header(level, text, header_id=None):
9893
return tag(text, "h" + str(level + 2), {"id": header_id})
9994

10095

101-
def paragraph(text):
102-
return tag(inject_class_links(text), "p")
96+
def paragraph(text, link_classes=True):
97+
if link_classes:
98+
text = inject_class_links(text)
99+
return tag(text, "p")
103100

104101

105102
def strong(text):
@@ -126,25 +123,6 @@ def code_block(lines):
126123
return tag("<br>".join(lines), "pre", {"class": "hljs python"})
127124

128125

129-
def header_link(text, header_id):
130-
""" Converts the given text into a header link (intra-document relative
131-
link). Example:
132-
>>> header_link("Some text", "chapter_id")
133-
>>> <a href="#chapter_id">Some text</a>
134-
"""
135-
return tag(text, "a", {"href":"#" + header_id})
136-
137-
138-
def class_link(cls, text):
139-
""" Generates an intra-document link for the given class. Example:
140-
>>> from labelbox import Project
141-
>>> class_link(Project, "blah")
142-
>>> <a href="#class_labelbox_schema_project">blah</a>
143-
"""
144-
header_id = "class_" + snake_case(qual_class_name(cls).replace(".", "_"))
145-
return header_link(text, header_id)
146-
147-
148126
def inject_class_links(text):
149127
""" Finds all occurences of known class names in the given text and
150128
replaces them with relative links to those classes.
@@ -154,7 +132,9 @@ def inject_class_links(text):
154132
matches = list(re.finditer(pattern, text))
155133
for match in reversed(matches):
156134
start, end = match.span()
157-
text = text[:start] + class_link(cls, match.group()) + text[end:]
135+
link = tag(match.group(), "a",
136+
{"href":"#" + snake_case(cls.__name__)})
137+
text = text[:start] + link + text[end:]
158138
return text
159139

160140

@@ -380,15 +360,17 @@ def generate_class(cls):
380360
text = []
381361
schema_class = issubclass(cls, Entity)
382362

383-
title = "Class " + cls.__module__ + "." + cls.__name__
384-
title_id = re.sub(r"\s+", "_", snake_case(title).lower())
363+
text.append(header(2, cls.__name__, snake_case(cls.__name__)))
364+
365+
package_and_superclasses = "Class " + cls.__module__ + "." + cls.__name__
385366
if schema_class:
386367
superclasses = [plugin.__name__ for plugin
387368
in (Updateable, Deletable, BulkDeletable)
388369
if issubclass(cls, plugin )]
389370
if superclasses:
390-
title += " (%s)" % ", ".join(superclasses)
391-
text.append(header(2, title, title_id))
371+
package_and_superclasses += " (%s)" % ", ".join(superclasses)
372+
package_and_superclasses += "."
373+
text.append(paragraph(package_and_superclasses, False))
392374

393375
text.append(preprocess_docstring(cls.__doc__))
394376

@@ -419,11 +401,11 @@ def generate_all():
419401
""" Generates the full HelpDocs API documentation article body. """
420402
text = []
421403
text.append(header(3, "General Classes"))
422-
text.append(unordered_list([qual_class_name(cls) for cls in GENERAL_CLASSES]))
404+
text.append(unordered_list([cls.__name__ for cls in GENERAL_CLASSES]))
423405
text.append(header(3, "Data Classes"))
424-
text.append(unordered_list([qual_class_name(cls) for cls in SCHEMA_CLASSES]))
406+
text.append(unordered_list([cls.__name__ for cls in SCHEMA_CLASSES]))
425407
text.append(header(3, "Error Classes"))
426-
text.append(unordered_list([qual_class_name(cls) for cls in ERROR_CLASSES]))
408+
text.append(unordered_list([cls.__name__ for cls in ERROR_CLASSES]))
427409

428410
text.append(header(1, "General classes"))
429411
text.extend(generate_class(cls) for cls in GENERAL_CLASSES)

0 commit comments

Comments
 (0)