From 398df15d71af412860227c05dc4f593704b998a5 Mon Sep 17 00:00:00 2001
From: Amir MOHAMMADI <amir.mohammadi@idiap.ch>
Date: Tue, 10 Nov 2020 12:25:28 +0100
Subject: [PATCH] [sphinx cli] Add more autodoc flags variants
---
bob/devtools/scripts/sphinx.py | 170 ++++++++++++++++++++++++++++++---
1 file changed, 155 insertions(+), 15 deletions(-)
diff --git a/bob/devtools/scripts/sphinx.py b/bob/devtools/scripts/sphinx.py
index 9ae00905..8aba8823 100644
--- a/bob/devtools/scripts/sphinx.py
+++ b/bob/devtools/scripts/sphinx.py
@@ -8,30 +8,87 @@ def sphinx():
@sphinx.command()
@click.argument(
- "sphix_configuration",
- default="doc/conf.py",
+ "sphix_configurations",
type=click.Path(exists=True, dir_okay=False),
required=False,
+ nargs=-1,
)
-def migrate_autodoc_flags(sphix_configuration):
- with open(sphix_configuration) as f:
- config = f.read()
+def migrate_autodoc_flags(sphix_configurations):
+ if not sphix_configurations:
+ sphix_configurations = ["doc/conf.py"]
+ for sphinx_config in sphix_configurations:
+ with open(sphinx_config) as f:
+ config = f.read()
- config = config.replace(
- """autodoc_default_flags = [
+ config = config.replace(
+ """autodoc_default_flags = [
'members',
'undoc-members',
'show-inheritance',
]""",
- """autodoc_default_options = {
+ """autodoc_default_options = {
"members": True,
"undoc-members": True,
"show-inheritance": True,
}""",
- )
+ )
- config = config.replace(
- """# We want to remove all private (i.e. _. or __.__) members
+ # another variant
+ config = config.replace(
+ """autodoc_default_flags = [
+ "members",
+ "undoc-members",
+ "show-inheritance",
+]""",
+ """autodoc_default_options = {
+ "members": True,
+ "undoc-members": True,
+ "show-inheritance": True,
+}""",
+ )
+
+ # another variant
+ config = config.replace(
+ """autodoc_default_flags = [
+ 'members',
+ 'undoc-members',
+ 'show-inheritance',
+]""",
+ """autodoc_default_options = {
+ "members": True,
+ "undoc-members": True,
+ "show-inheritance": True,
+}""",
+ )
+
+ # another variant
+ config = config.replace(
+ """autodoc_default_flags = [
+ 'members',
+ 'undoc-members',
+ 'inherited-members',
+ 'show-inheritance',
+ ]""",
+ """autodoc_default_options = {
+ "members": True,
+ "undoc-members": True,
+ "inherited-members": True,
+ "show-inheritance": True,
+}""",
+ )
+
+ # another variant
+ config = config.replace(
+ """autodoc_default_flags = ["members", "undoc-members", "show-inheritance"]""",
+ """autodoc_default_options = {
+ "members": True,
+ "undoc-members": True,
+ "show-inheritance": True,
+}""",
+ )
+
+ config = config.replace(
+ """# We want to remove all private (i.e. _. or __.__) members
# that are not in the list of accepted functions
accepted_private_functions = ['__array__']
@@ -51,8 +108,91 @@ def member_function_test(app, what, name, obj, skip, options):
def setup(app):
app.connect('autodoc-skip-member', member_function_test)
""",
- "",
- )
+ "",
+ )
+
+ # another variant
+ config = config.replace(
+ """# We want to remove all private (i.e. _. or __.__) members
+# that are not in the list of accepted functions
+accepted_private_functions = ['__array__']
+
+
+def member_function_test(app, what, name, obj, skip, options):
+ # test if we have a private function
+ if len(name) > 1 and name[0] == '_':
+ # test if this private function should be allowed
+ if name not in accepted_private_functions:
+ # omit privat functions that are not in the list of accepted private functions
+ return skip
+ else:
+ # test if the method is documented
+ if not hasattr(obj, '__doc__') or not obj.__doc__:
+ return skip
+ return False
+
+
+def setup(app):
+ app.connect('autodoc-skip-member', member_function_test)
+""",
+ "",
+ )
+
+ # another variant
+ config = config.replace(
+ """# We want to remove all private (i.e. _. or __.__) members
+# that are not in the list of accepted functions
+accepted_private_functions = ["__array__"]
+
+
+def member_function_test(app, what, name, obj, skip, options):
+ # test if we have a private function
+ if len(name) > 1 and name[0] == "_":
+ # test if this private function should be allowed
+ if name not in accepted_private_functions:
+ # omit privat functions that are not in the list of accepted private functions
+ return skip
+ else:
+ # test if the method is documented
+ if not hasattr(obj, "__doc__") or not obj.__doc__:
+ return skip
+ return False
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", member_function_test)
+""",
+ "",
+ )
+
+ # another variant
+ config = config.replace(
+ """
+# We want to remove all private (i.e. _. or __.__) members
+# that are not in the list of accepted functions
+accepted_private_functions = ["__array__"]
+
+
+def member_function_test(app, what, name, obj, skip, options):
+ # test if we have a private function
+ if len(name) > 1 and name[0] == "_":
+ # test if this private function should be allowed
+ if name not in accepted_private_functions:
+ # omit private functions that are not in the list of accepted private
+ # functions
+ return skip
+ else:
+ # test if the method is documented
+ if not hasattr(obj, "__doc__") or not obj.__doc__:
+ return skip
+ return False
+
+
+def setup(app):
+ app.connect("autodoc-skip-member", member_function_test)
+""",
+ "",
+ )
- with open(sphix_configuration, "w") as f:
- f.write(config)
+ with open(sphinx_config, "w") as f:
+ f.write(config)
--
GitLab