Merge branch 'sphinx-cli' into 'master'

Add a sphinx command to help with migrating to sphinx 3

See merge request !188

bob/devtools/scripts/sphinx.py

+import click
+
+
+@click.group()
+def sphinx():
+    pass
+
+
+@sphinx.command()
+@click.argument(
+    "sphix_configurations",
+    type=click.Path(exists=True, dir_okay=False),
+    required=False,
+    nargs=-1,
+)
+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 = [
+  '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',
+    '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__']
+
+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 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(sphinx_config, "w") as f:
+            f.write(config)

bob/devtools/templates/doc/conf.py

@@ -223,7 +223,11 @@ rst_epilog = """
 # Default processing flags for sphinx
 autoclass_content = "class"
 autodoc_member_order = "bysource"
-autodoc_default_flags = ["members", "undoc-members", "show-inheritance"]
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
 
 
 sphinx_requirements = "extra-intersphinx.txt"

conda/meta.yaml

@@ -107,6 +107,8 @@ test:
     - bdt gitlab get-pipelines --help
     - bdt gitlab graph --help
     - bdt gitlab badges --help
+    - bdt sphinx --help
+    - bdt sphinx migrate-autodoc-flags --help
     - sphinx-build -aEW ${PREFIX}/share/doc/{{ name }}/doc sphinx
     {% if not os.path.exists('sphinx') %}
     - if [ -n "${CI_PROJECT_DIR}" ]; then mv sphinx "${CI_PROJECT_DIR}/"; fi

doc/conf.py

@@ -221,11 +221,11 @@ rst_epilog = """
 # Default processing flags for sphinx
 autoclass_content = "class"
 autodoc_member_order = "bysource"
-autodoc_default_flags = [
-    "members",
-    "undoc-members",
-    "show-inheritance",
-]
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "show-inheritance": True,
+}
 
 # Adds simplejson, pyzmq links
 # intersphinx_mapping['http://simplejson.readthedocs.io/en/stable/'] = None

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",