Repository: Lightning-Universe/lightning-flash

Issue:
Drop `autodatasources` extension in favour of docstrings
Since each classmethod will exist on the actual data module now, we should remove the `autodatasources` stuff in favour of having comprehensive docstrings on the relevant methods.


Discussion:

Resolving patch:
diff --git a/docs/extensions/autodatasources.py b/docs/extensions/autodatasources.py
deleted file mode 100644
--- a/docs/extensions/autodatasources.py
+++ /dev/null
@@ -1,81 +0,0 @@
-# Copyright The PyTorch Lightning team.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-import importlib
-import os
-
-from docutils import nodes
-from docutils.parsers.rst import Directive
-from docutils.statemachine import StringList
-from jinja2 import ChoiceLoader, Environment, FileSystemLoader, FunctionLoader
-from sphinx.util.nodes import nested_parse_with_titles
-
-
-class TemplateLoader:
-    def __init__(self):
-        self.templates = {}
-
-    def __call__(self, name: str):
-        return self.templates.get(name, None)
-
-    def add_template(self, name: str, content: str):
-        self.templates[name] = content
-
-
-_PATH_HERE = os.path.abspath(os.path.dirname(__file__))
-TEMPLATE_LOADER = TemplateLoader()
-ENVIRONMENT = Environment(
-    loader=ChoiceLoader([FileSystemLoader(os.path.join(_PATH_HERE, "templates")), FunctionLoader(TEMPLATE_LOADER)])
-)
-
-
-class AutoDataSources(Directive):
-    has_content = True
-    required_arguments = 2
-    optional_arguments = 0
-
-    def run(self):
-        data_module_path, data_module_name = self.arguments
-
-        string_list = self.content
-        source = string_list.source(0)
-        TEMPLATE_LOADER.add_template(data_module_name, "\n".join(string_list.data))
-
-        data_module = getattr(importlib.import_module(data_module_path), data_module_name)
-
-        class PatchedInputTransform(data_module.input_transform_cls):
-            """TODO: This is a hack to prevent default transforms form being created"""
-
-            @staticmethod
-            def _resolve_transforms(_):
-                return None
-
-        input_transform = PatchedInputTransform()
-        inputs = {input: input_transform.input_of_name(input) for input in input_transform.available_inputs()}
-
-        ENVIRONMENT.get_template("base.rst")
-
-        rendered_content = ENVIRONMENT.get_template(data_module_name).render(
-            data_module=f":class:`~{data_module_path}.{data_module_name}`",
-            data_module_raw=data_module_name,
-            inputs=inputs,
-        )
-
-        node = nodes.section()
-        node.document = self.state.document
-        nested_parse_with_titles(self.state, StringList(rendered_content.split("\n"), source), node)
-        return node.children
-
-
-def setup(app):
-    app.add_directive("autodatasources", AutoDataSources)
diff --git a/docs/source/conf.py b/docs/source/conf.py
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -23,7 +23,6 @@
 _PATH_ROOT = os.path.join(_PATH_HERE, "..", "..")
 _PATH_RAW_NB = os.path.join(_PATH_ROOT, "_notebooks")
 sys.path.insert(0, os.path.abspath(_PATH_ROOT))
-sys.path.insert(0, os.path.abspath(os.path.join(_PATH_HERE, "..", "extensions")))
 sys.path.append(os.path.join(_PATH_RAW_NB, ".actions"))
 
 _SHOULD_COPY_NOTEBOOKS = True
@@ -112,20 +111,17 @@ def _transform_changelog(path_in: str, path_out: str) -> None:
     "sphinx.ext.doctest",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
-    # 'sphinx.ext.coverage',
     "sphinx.ext.viewcode",
     "sphinx.ext.autosummary",
     "sphinx.ext.napoleon",
     "sphinx.ext.imgmath",
-    "recommonmark",
-    # 'sphinx.ext.autosectionlabel',
+    "myst_parser",
     "nbsphinx",
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_paramlinks",
     "sphinx_togglebutton",
     "pt_lightning_sphinx_theme.extensions.lightning_tutorials",
-    "autodatasources",
 ]
 
 # autodoc: Default to members and undoc-members
@@ -137,15 +133,30 @@ def _transform_changelog(path_in: str, path_out: str) -> None:
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]
 
+# https://berkeley-stat159-f17.github.io/stat159-f17/lectures/14-sphinx..html#conf.py-(cont.)
+# https://stackoverflow.com/questions/38526888/embed-ipython-notebook-in-sphinx-document
+# I execute the notebooks manually in advance. If notebooks test the code,
+# they should be run at build time.
+nbsphinx_execute = "never"
+nbsphinx_allow_errors = True
+nbsphinx_requirejs_path = ""
+
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = ["generated/PULL_REQUEST_TEMPLATE.md"]
 
+# myst-parser, forcing to parse all html pages with mathjax
+# https://github.com/executablebooks/MyST-Parser/issues/394
+myst_update_mathjax = False
+
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
 #
-source_suffix = [".rst", ".md"]
+source_parsers = {".rst": "restructuredtext", ".txt": "markdown", ".md": "markdown", ".ipynb": "nbsphinx"}
+
+# The master toctree document.
+master_doc = "index"
 
 needs_sphinx = "4.0"
 


Test patch: