diff --git a/bob/devtools/scripts/sphinx.py b/bob/devtools/scripts/sphinx.py new file mode 100644 index 0000000000000000000000000000000000000000..9ae009057e5443756f56c91b864763337e163325 --- /dev/null +++ b/bob/devtools/scripts/sphinx.py @@ -0,0 +1,58 @@ +import click + + +@click.group() +def sphinx(): + pass + + +@sphinx.command() +@click.argument( + "sphix_configuration", + default="doc/conf.py", + type=click.Path(exists=True, dir_okay=False), + required=False, +) +def migrate_autodoc_flags(sphix_configuration): + with open(sphix_configuration) as f: + config = f.read() + + 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__'] + +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) +""", + "", + ) + + with open(sphix_configuration, "w") as f: + f.write(config) diff --git a/setup.py b/setup.py index f22e6f62aecfc1b93cafa991570d2864c70a7532..5a9eb12b3628f7c762ee1a90aa3bda20920cf992 100644 --- a/setup.py +++ b/setup.py @@ -52,6 +52,7 @@ setup( "dav = bob.devtools.scripts.dav:dav", "local = bob.devtools.scripts.local:local", "gitlab = bob.devtools.scripts.gitlab:gitlab", + "sphinx = bob.devtools.scripts.sphinx:sphinx", ], "bdt.gitlab.cli": [ "badges = bob.devtools.scripts.badges:badges",