From 7228a545d77f7a76ba57adc97f14caaa2e21f7e4 Mon Sep 17 00:00:00 2001 From: Ales Erjavec Date: Tue, 13 Mar 2018 14:39:27 +0100 Subject: [PATCH 1/2] setup.py: Install widget help files * Selectively disable numpy.distutils install_data command * Add --with[out]-htmlhelp options for `sdist` and `build` commands (by default the documentation is build if sphinx is installed) --- Orange/widgets/__init__.py | 7 +- requirements-dev.txt | 2 + setup.cfg | 13 ++- setup.py | 188 +++++++++++++++++++++++++++++++++++-- 4 files changed, 197 insertions(+), 13 deletions(-) diff --git a/Orange/widgets/__init__.py b/Orange/widgets/__init__.py index 5a07314098c..38116530629 100644 --- a/Orange/widgets/__init__.py +++ b/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/", ""), ) diff --git a/requirements-dev.txt b/requirements-dev.txt index af85ddc217f..b5637ead302 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -1,2 +1,4 @@ pylint radon +# for build_htmlhelp command +sphinx>=1.5 \ No newline at end of file diff --git a/setup.cfg b/setup.cfg index e735e907d6c..f5d02fd9e10 100644 --- a/setup.cfg +++ b/setup.cfg @@ -1,4 +1,9 @@ -[build_sphinx] -source-dir = doc -build-dir = doc/build -all_files = 1 \ No newline at end of file +[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 diff --git a/setup.py b/setup.py index eca55208076..e4c5b179d19 100755 --- a/setup.py +++ b/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,8 +240,6 @@ 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( @@ -242,13 +247,181 @@ def initialize_options(self): ) +# ${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() From 97b1a750a969443ad134d56e88f2c4e6be979ed6 Mon Sep 17 00:00:00 2001 From: Ales Erjavec Date: Tue, 9 Oct 2018 13:01:59 +0200 Subject: [PATCH 2/2] doc: Remove unused and non-functional .md parser --- doc/visual-programming/source/conf.py | 3 +-- .../source/orange_extras.py | 25 ------------------- requirements-doc.txt | 2 -- 3 files changed, 1 insertion(+), 29 deletions(-) delete mode 100644 doc/visual-programming/source/orange_extras.py diff --git a/doc/visual-programming/source/conf.py b/doc/visual-programming/source/conf.py index 0b6911fe3d0..3068e961c10 100644 --- a/doc/visual-programming/source/conf.py +++ b/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' diff --git a/doc/visual-programming/source/orange_extras.py b/doc/visual-programming/source/orange_extras.py deleted file mode 100644 index 67f21ac1b63..00000000000 --- a/doc/visual-programming/source/orange_extras.py +++ /dev/null @@ -1,25 +0,0 @@ -from bs4 import BeautifulSoup -from docutils import nodes - -import recommonmark.parser as parser -from recommonmark.parser import CommonMarkParser,\ - inline_html as old_inline_html - -__all__ = ['CommonMarkParser'] - - -def create_image_node(block): - soup = BeautifulSoup(block.c, 'html.parser') - images = soup.find_all('img') - - for img in images: - img_node = nodes.image() - img_node['uri'] = img.attrs.pop('src') - for attr, value in img.attrs.items(): - img_node[attr] = value - return img_node - - -def inline_html(block): - return create_image_node(block) or old_inline_html(block) -parser.inline_html = inline_html diff --git a/requirements-doc.txt b/requirements-doc.txt index 11baf5d476e..dcc31f22ca0 100644 --- a/requirements-doc.txt +++ b/requirements-doc.txt @@ -1,6 +1,4 @@ -beautifulsoup4 docutils numpydoc -recommonmark>=0.1.1 Sphinx>=1.3 PyQt5