add sphinx auto docs

Author: xinntao

.gitignore

@@ -6,6 +6,9 @@ tb_logger/*
 wandb/*
 tmp/*
 
+docs/api
+scripts/__init__.py
+
 *.DS_Store
 .idea
 

docs/api.rst

@@ -0,0 +1,97 @@
+import os
+from os import path as osp
+
+
+def scandir(dir_path, suffix=None, recursive=False, full_path=False):
+    """Scan a directory to find the interested files.
+
+    Args:
+        dir_path (str): Path of the directory.
+        suffix (str | tuple(str), optional): File suffix that we are
+            interested in. Default: None.
+        recursive (bool, optional): If set to True, recursively scan the
+            directory. Default: False.
+        full_path (bool, optional): If set to True, include the dir_path.
+            Default: False.
+
+    Returns:
+        A generator for all the interested files with relative paths.
+    """
+
+    if (suffix is not None) and not isinstance(suffix, (str, tuple)):
+        raise TypeError('"suffix" must be a string or tuple of strings')
+
+    root = dir_path
+
+    def _scandir(dir_path, suffix, recursive):
+        for entry in os.scandir(dir_path):
+            if not entry.name.startswith('.') and entry.is_file():
+                if full_path:
+                    return_path = entry.path
+                else:
+                    return_path = osp.relpath(entry.path, root)
+
+                if suffix is None:
+                    yield return_path
+                elif return_path.endswith(suffix):
+                    yield return_path
+            else:
+                if recursive:
+                    yield from _scandir(entry.path, suffix=suffix, recursive=recursive)
+                else:
+                    continue
+
+    return _scandir(dir_path, suffix=suffix, recursive=recursive)
+
+
+# specifically generate a fake __init__.py for scripts folder to generate docs
+with open('../scripts/__init__.py', 'w') as f:
+    pass
+
+module_name_list = ['basicsr', 'scripts']
+for module_name in module_name_list:
+    cur_dir = osp.abspath(osp.dirname(__file__))
+    output_dir = osp.join(cur_dir, 'api')
+    module_dir = osp.join(osp.dirname(cur_dir), module_name)
+    os.makedirs(output_dir, exist_ok=True)
+
+    api_content = f'{module_name} API\n=========================\n'
+    submodule_name_list = []
+
+    for path in sorted(scandir(module_dir, suffix='.py', recursive=True)):
+        if path in ['__init__.py', 'version.py']:
+            continue
+
+        path = f'{module_name}.' + path.replace('\\', '/').replace('/', '.').replace('.py', '.rst')
+
+        # create .rst file
+        output_rst = osp.join(output_dir, path)
+        with open(output_rst, 'w') as f:
+            # write contents
+            title = path.replace('.rst', '').replace('_', '\\_')
+            content = f'{title}\n===================================================================================\n'
+            automodule = path.replace('.rst', '')
+            content += f'\n.. automodule:: {automodule}'
+            content += r'''
+    :members:
+    :undoc-members:
+    :show-inheritance:
+    '''
+            f.write(content)
+
+        # add to api.rst
+        submodule_name = path.split('.')[1]
+        if submodule_name not in submodule_name_list:
+            submodule_name_list.append(submodule_name)
+            api_content += f'\n\n{module_name}.{submodule_name}\n-----------------------------------------------------'
+            api_content += r'''
+.. toctree::
+    :maxdepth: 4
+
+'''
+
+        api_content += f'    {automodule}\n'
+
+    # write to api.rst
+    with open(os.path.join(output_dir, f'api_{module_name}.rst'), 'w') as f:
+        f.write(api_content)

docs/auto_generate_api.py

@@ -11,15 +11,15 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 #
 import os
-# import subprocess
+import subprocess
 import sys
 
 sys.path.insert(0, os.path.abspath('..'))
 
 # -- Project information -----------------------------------------------------
 
 project = 'BasicSR'
-copyright = '2018-2021, BasicSR Authors'
+copyright = '2018-2022, BasicSR Authors'
 author = 'BasicSR Authors'
 
 # -- General configuration ---------------------------------------------------
@@ -58,3 +58,26 @@
 
 # The master toctree document.
 master_doc = 'index'
+
+# def run_apidoc(_):
+#     # automatically generate api docs
+#     modules = ['basicsr']
+#     for module in modules:
+#         cur_dir = os.path.abspath(os.path.dirname(__file__))
+#         output_path = os.path.join(cur_dir, 'api')
+#         cmd_path = 'sphinx-apidoc'
+#         if hasattr(sys, 'real_prefix'):  # Check to see if we are in a virtualenv
+#             # If we are, assemble the path manually
+#             cmd_path = os.path.abspath(os.path.join(sys.prefix, 'bin', 'sphinx-apidoc'))
+#         subprocess.check_call([cmd_path, '-e', '-o', output_path, '../' + module, '--force'])
+
+# def setup(app):
+#     app.connect('builder-inited', run_apidoc)
+
+
+def auto_generate_api(app):
+    subprocess.run(['python', './auto_generate_api.py'])
+
+
+def setup(app):
+    app.connect('builder-inited', auto_generate_api)

docs/conf.py

@@ -2,10 +2,11 @@ Welcome to BasicSR's documentation!
 ===================================
 
 .. toctree::
-   :maxdepth: 3
+   :maxdepth: 4
    :caption: API
 
-   api.rst
+   api/api_basicsr.rst
+   api/api_scripts.rst
 
 Indices and tables
 ==================