Merge pull request #3345 from ales-erjavec/install-help-files

[ENH] Install widget help files

Orange/widgets/__init__.py

@@ -25,7 +25,8 @@ def widget_discovery(discovery):
 
 WIDGET_HELP_PATH = (
     ("{DEVELOP_ROOT}/doc/visual-programming/build/htmlhelp/index.html", None),
-#     os.path.join(sysconfig.get_path("data"),
-#                  "share", "doc", "Orange-{}".format(Orange.__version__)),
-    ("https://docs.orange.biolab.si/3/visual-programming/", "")
+    (os.path.join(sysconfig.get_path("data"),
+                  "share/help/en/orange3/htmlhelp/index.html"),
+     None),
+    ("https://docs.orange.biolab.si/3/visual-programming/", ""),
 )

doc/visual-programming/source/conf.py

@@ -47,8 +47,7 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-source_suffix = ['.rst', '.md']
-source_parsers = {".md": "orange_extras.CommonMarkParser"}
+source_suffix = ['.rst']
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'

requirements-dev.txt

@@ -1,2 +1,4 @@
 pylint
 radon
+# for build_htmlhelp command
+sphinx>=1.5

requirements-doc.txt

@@ -1,6 +1,4 @@
-beautifulsoup4
 docutils
 numpydoc
-recommonmark>=0.1.1
 Sphinx>=1.3
 PyQt5

setup.cfg

@@ -1,4 +1,9 @@
-[build_sphinx]
-source-dir = doc
-build-dir = doc/build
-all_files = 1
+[config]
+# applies to sdist and build commands
+with-htmlhelp = 1
+
+[aliases]
+# build a sdist and a wheel release with included widget help
+# files
+build_release_sdist = clean build_htmlhelp sdist
+build_release_wheel = clean build_htmlhelp bdist_wheel

setup.py

@@ -15,7 +15,16 @@
     from setuptools import setup
     have_numpy = False
 
+
+try:
+    from sphinx.setup_command import BuildDoc
+    have_sphinx = True
+except ImportError:
+    have_sphinx = False
+
 from distutils.command.build_ext import build_ext
+from distutils.command import install_data, sdist, config, build
+
 
 NAME = 'Orange3'
 
@@ -81,9 +90,7 @@
 }
 
 
-EXTRAS_REQUIRE = {
-    ':python_version<="3.4"': ["typing"],
-}
+DATA_FILES = []
 
 # Return the git revision as a string
 def git_version():
@@ -233,22 +240,188 @@ def run(self):
         ''', shell=True, cwd=os.path.dirname(os.path.abspath(__file__))))
 
 
-
-
 class build_ext_error(build_ext):
     def initialize_options(self):
         raise SystemExit(
             "Cannot compile extensions. numpy is required to build Orange."
         )
 
 
+# ${prefix} relative install path for html help files
+DATAROOTDIR = "share/help/en/orange3/htmlhelp/"
+
+
+def findall(startdir, followlinks=False, ):
+    files = (
+        os.path.join(base, file)
+        for base, dirs, files in os.walk(startdir, followlinks=followlinks)
+        for file in files
+    )
+    return filter(os.path.isfile, files)
+
+
+def find_htmlhelp_files(subdir):
+    data_files = []
+    thisdir = os.path.dirname(__file__)
+    sourcedir = os.path.join(thisdir, subdir)
+    files = filter(
+        # filter out meta files
+        lambda path: not path.endswith((".hhc", ".hhk", ".hhp", ".stp")),
+        findall(sourcedir)
+    )
+    for file in files:
+        relpath = os.path.relpath(file, start=subdir)
+        data_files.append(
+            (os.path.join(DATAROOTDIR, os.path.dirname(relpath)), [file])
+        )
+    return data_files
+
+
+def add_with_option(option, help="", default=None, ):
+    """
+    A class decorator that adds a boolean --with(out)-option cmd line switch
+    to a distutils.cmd.Command class
+
+    Parameters
+    ----------
+    option : str
+        Name of the option without the 'with-' part i.e. passing foo will
+        create a `--with-foo` and `--without-foo` options
+    help : str
+        Help for `cmd --help`. This should document the positive option (i.e.
+        --with-foo)
+    default : Optional[bool]
+        The default state.
+
+    Returns
+    -------
+    command : Command
+
+    Examples
+    --------
+    >>> @add_with_option("foo", "Build with foo enabled", default=False)
+    >>> class foobuild(build):
+    >>>    def run(self):
+    >>>        if self.with_foo:
+    >>>            ...
+
+    """
+    def decorator(cmdclass):
+        # type: (Type[Command]) -> Type[Command]
+        cmdclass.user_options = getattr(cmdclass, "user_options", []) + [
+            ("with-" + option, None, help),
+            ("without-" + option, None, ""),
+        ]
+        cmdclass.boolean_options = getattr(cmdclass, "boolean_options", []) + [
+            ("with-" + option,),
+        ]
+        cmdclass.negative_opt = dict(
+            getattr(cmdclass, "negative_opt", {}), **{
+                "without-" + option: "with-" + option
+            }
+        )
+        setattr(cmdclass, "with_" + option, default)
+        return cmdclass
+    return decorator
+
+
+_HELP = "Build and include html help files in the distribution"
+
+
+@add_with_option("htmlhelp", _HELP)
+class config(config.config):
+    # just record the with-htmlhelp option for sdist and build's default
+    pass
+
+
+@add_with_option("htmlhelp", _HELP)
+class sdist(sdist.sdist):
+    # build_htmlhelp to fill in distribution.data_files which are then included
+    # in the source dist.
+    sub_commands = sdist.sdist.sub_commands + [
+        ("build_htmlhelp", lambda self: self.with_htmlhelp)
+    ]
+
+    def finalize_options(self):
+        super().finalize_options()
+        self.set_undefined_options(
+            "config", ("with_htmlhelp", "with_htmlhelp")
+        )
+
+
+@add_with_option("htmlhelp", _HELP)
+class build(build.build):
+    sub_commands = build.build.sub_commands + [
+        ("build_htmlhelp", lambda self: self.with_htmlhelp)
+    ]
+
+    def finalize_options(self):
+        super().finalize_options()
+        self.set_undefined_options(
+            "config", ("with_htmlhelp", 'with_htmlhelp')
+        )
+
+
+# Does the sphinx source for widget help exist the sources are in the checkout
+# but not in the source distribution (sdist). The sdist already contains
+# build html files.
+HAVE_SPHINX_SOURCE = os.path.isdir("doc/visual-programming/source")
+# Doest the build htmlhelp documentation exist
+HAVE_BUILD_HTML = os.path.exists("doc/visual-programming/build/htmlhelp/index.html")
+
+if have_sphinx and HAVE_SPHINX_SOURCE:
+    class build_htmlhelp(BuildDoc):
+        def initialize_options(self):
+            super().initialize_options()
+            self.build_dir = "doc/visual-programming/build"
+            self.source_dir = "doc/visual-programming/source"
+            self.builder = "htmlhelp"
+            self.version = VERSION
+
+        def run(self):
+            super().run()
+            helpdir = os.path.join(self.build_dir, "htmlhelp")
+            files = find_htmlhelp_files(helpdir)
+            # add the build files to distribution
+            self.distribution.data_files.extend(files)
+
+else:
+    # without sphinx we need the docs to be already build. i.e. from a
+    # source dist build --with-htmlhelp
+    class build_htmlhelp(Command):
+        user_options = [('build-dir=', None, 'Build directory')]
+        build_dir = None
+
+        def initialize_options(self):
+            self.build_dir = "doc/visual-programming/build"
+
+        def finalize_options(self):
+            pass
+
+        def run(self):
+            helpdir = os.path.join(self.build_dir, "htmlhelp")
+            if not (os.path.isdir(helpdir)
+                    and os.path.isfile(os.path.join(helpdir, "index.html"))):
+                self.warn("Sphinx is needed to build help files. Skipping.")
+                return
+            files = find_htmlhelp_files(os.path.join(helpdir))
+            # add the build files to distribution
+            self.distribution.data_files.extend(files)
+
+
 def setup_package():
     write_version_py()
     cmdclass = {
         'lint': LintCommand,
         'coverage': CoverageCommand,
+        'config': config,
+        'sdist': sdist,
+        'build': build,
+        'build_htmlhelp': build_htmlhelp,
+        # Use install_data from distutils, not numpy.distutils.
+        # numpy.distutils insist all data files are installed in site-packages
+        'install_data': install_data.install_data
     }
-
     if have_numpy:
         extra_args = {
             "configuration": configuration
@@ -260,6 +433,7 @@ def setup_package():
         # query our install dependencies
         extra_args = {}
         cmdclass["build_ext"] = build_ext_error
+
     setup(
         name=NAME,
         version=FULLVERSION,
@@ -273,6 +447,7 @@ def setup_package():
         classifiers=CLASSIFIERS,
         packages=PACKAGES,
         package_data=PACKAGE_DATA,
+        data_files=DATA_FILES,
         install_requires=INSTALL_REQUIRES,
         extras_require=EXTRAS_REQUIRE,
         entry_points=ENTRY_POINTS,
@@ -282,5 +457,6 @@ def setup_package():
         **extra_args
     )
 
+
 if __name__ == '__main__':
     setup_package()