# (C) Copyright 2004-2023 Enthought, Inc., Austin, TX
# All rights reserved.
#
# This software is provided without warranty under the terms of the BSD
# license included in LICENSE.txt and may be redistributed only under
# the conditions described in the aforementioned license. The license
# is also available online at http://www.enthought.com/licenses/BSD.txt
#
# Thanks for using Enthought open source!

""" A Traits UI demo that borrows heavily from the design of the wxPython demo.

This copy of the demo application will only be maintained until ``ets-demo``
is released and distributed. This allows other ETS packages to continue to be
able to import the demo application until ``ets-demo`` is released.
(enthought/traitsui#950)
"""

import contextlib
import glob
from io import StringIO
import operator
import os
from os import listdir
from os.path import (
    abspath,
    basename,
    dirname,
    exists,
    isabs,
    isdir,
    join,
    split,
    splitext,
)
import sys
import token
import tokenize
import traceback


from configobj import ConfigObj

from pyface.api import ImageResource
from traits.api import (
    Any,
    Bool,
    Button,
    cached_property,
    Code,
    Dict,
    HasPrivateTraits,
    HasTraits,
    HTML,
    Instance,
    Property,
    Str,
)
from traitsui.api import (
    Action,
    CodeEditor,
    Handler,
    Heading,
    HGroup,
    HSplit,
    HTMLEditor,
    Include,
    InstanceEditor,
    Item,
    ModelView,
    ObjectTreeNode,
    ShellEditor,
    spring,
    Tabbed,
    ToolBar,
    TreeEditor,
    TreeNodeObject,
    UIInfo,
    UItem,
    VGroup,
    View,
    VSplit,
)


# -------------------------------------------------------------------------
#  Global data:
# -------------------------------------------------------------------------

# Define the code used to populate the 'execfile' dictionary:
exec_str = """from traits.api import *

"""

# The name of the file being looked up for the description of a directory
DESCRIPTION_RST_FILENAME = "index.rst"

# ----------------------------------------------------------------------------
#  Return a 'user-friendly' name for a specified string:
# ----------------------------------------------------------------------------


def user_name_for(name):
    name = name.replace("_", " ")
    return name[:1].upper() + name[1:]


# -------------------------------------------------------------------------
#  Parses the contents of a specified source file into module comment and
#  source text:
# -------------------------------------------------------------------------


def extract_docstring_from_source(source):
    """Return module docstring and source code from python source code.

    Parameters
    ----------
    source : Str
        Python source code.

    Returns
    -------
    docstring : str
        The first module-level string; i.e. the module docstring.
    source : str
        The source code, sans docstring.
    """
    # Reset file and generate python tokens
    f = StringIO(source)
    python_tokens = tokenize.generate_tokens(f.readline)

    for ttype, tstring, tstart, tend, tline in python_tokens:
        token_name = token.tok_name[ttype]
        if token_name == "STRING" and tstart[1] == 0:
            break
    else:
        # No docstrings found. Return blank docstring and all the source.
        return "", source.strip()

    source_lines = source.splitlines()

    # Extract module docstring lines and recombine
    docstring = eval("\n".join(source_lines[tstart[0] - 1 : tend[0]]))
    source_lines = source_lines[: tstart[0] - 1] + source_lines[tend[0] :]
    source = "\n".join(source_lines)
    source = source.strip()

    return docstring, source


def parse_source(file_name):
    """Return module docstring and source code from python source file.

    Returns
    -------
    docstring : str
        The first module-level string; i.e. the module docstring.
    source : str
        The source code, sans docstring.
    """
    try:
        source_code = _read_file(file_name)
        return extract_docstring_from_source(source_code)
    except Exception:
        # Print an error message instead of failing silently.
        # Ideally, the message would be output to the "log" tab.
        traceback_text = traceback.format_exc()
        error_fmt = """Sorry, something went wrong.\n\n{}"""
        error_msg = error_fmt.format(traceback_text)
        return (error_msg, "")


def _read_file(path, mode='r', encoding='utf8'):
    """Returns the contents of a specified text file."""
    with open(path, mode, encoding=encoding) as fh:
        result = fh.read()
    return result


# -------------------------------------------------------------------------
#  'DemoFileHandler' class:
# -------------------------------------------------------------------------


@contextlib.contextmanager
def _set_stdout(std_out):
    stdout, stderr = sys.stdout, sys.stderr
    try:
        sys.stdout = sys.stderr = std_out
        yield std_out
    finally:
        sys.stdout, sys.stderr = stdout, stderr


class DemoFileHandler(Handler):

    # -------------------------------------------------------------------------
    #  Trait definitions:
    # -------------------------------------------------------------------------

    #: Run the demo file
    run_button = Button(image=ImageResource("run"), label="Run")

    #: The current 'info' object (for use by the 'write' method):
    info = Instance(UIInfo)

    def _run_button_changed(self):
        demo_file = self.info.object
        with _set_stdout(self):
            demo_file.run_code()

    def init(self, info):
        # Save the reference to the current 'info' object:
        self.info = info
        demo_file = info.object
        with _set_stdout(self):
            demo_file.init()
        return True

    def closed(self, info, is_ok):
        """Closes the view."""
        demo_file = info.object
        if hasattr(demo_file, 'demo'):
            demo_file.demo = None

    # -------------------------------------------------------------------------
    #  Handles 'print' output:
    # -------------------------------------------------------------------------

    def write(self, text):
        demo_file = self.info.object
        demo_file.log += text

    def flush(self):
        pass


# Create a singleton instance:
demo_file_handler = DemoFileHandler()


class DemoError(HasPrivateTraits):

    # -------------------------------------------------------------------------
    #  Trait definitions:
    # -------------------------------------------------------------------------

    #: The error message text:
    msg = Code()

    # -------------------------------------------------------------------------
    #  Traits view definitions:
    # -------------------------------------------------------------------------

    traits_view = View(
        VGroup(
            Heading("Error in source file"),
            Item("msg", style="custom", show_label=False),
        )
    )


class DemoButton(HasPrivateTraits):

    # -------------------------------------------------------------------------
    #  Trait definitions:
    # -------------------------------------------------------------------------

    #: The demo to be launched via a button:
    demo = Instance(HasTraits)

    #: The demo view item to use:
    demo_item = Item(
        "demo",
        show_label=False,
        editor=InstanceEditor(label="Run demo...", kind="live"),
    )

    # -------------------------------------------------------------------------
    #  Traits view definitions:
    # -------------------------------------------------------------------------

    traits_view = View(
        VGroup(
            VGroup(Heading("Click the button to run the demo:"), "20"),
            HGroup(spring, Include("demo_item"), spring),
        ),
        resizable=True,
    )


class ModalDemoButton(DemoButton):

    # -------------------------------------------------------------------------
    #  Trait definitions:
    # -------------------------------------------------------------------------

    #: The demo view item to use:
    demo_item = Item(
        "demo",
        show_label=False,
        editor=InstanceEditor(label="Run demo...", kind="modal"),
    )


class DemoTreeNodeObject(TreeNodeObject):

    # -------------------------------------------------------------------------
    #  Trait definitions:
    # -------------------------------------------------------------------------

    #: Cached result of 'tno_has_children':
    _has_children = Any()

    #: Cached result of 'tno_get_children':
    _get_children = Any()

    # -------------------------------------------------------------------------
    #  Returns whether chidren of this object are allowed or not:
    # -------------------------------------------------------------------------

    def tno_allows_children(self, node):
        """Returns whether chidren of this object are allowed or not."""
        return self.allows_children

    # -------------------------------------------------------------------------
    #  Returns whether or not the object has children:
    # -------------------------------------------------------------------------

    def tno_has_children(self, node=None):
        """Returns whether or not the object has children."""
        if self._has_children is None:
            self._has_children = self.has_children()

        return self._has_children

    # -------------------------------------------------------------------------
    #  Gets the object's children:
    # -------------------------------------------------------------------------

    def tno_get_children(self, node):
        """Gets the object's children."""
        if self._get_children is None:
            self._get_children = self.get_children()

        return self._get_children

    # -------------------------------------------------------------------------
    #  Returns whether or not the object has children:
    # -------------------------------------------------------------------------

    def has_children(self, node):
        """Returns whether or not the object has children."""
        raise NotImplementedError

    # -------------------------------------------------------------------------
    #  Gets the object's children:
    # -------------------------------------------------------------------------

    def get_children(self):
        """Gets the object's children."""
        raise NotImplementedError


class DemoFileBase(DemoTreeNodeObject):
    #: Parent of this file:
    parent = Any()

    #: Name of file system path to this file:
    path = Property(observe='parent.path,name')

    #: Name of the file:
    name = Str()

    #: UI form of the 'name':
    nice_name = Property()

    #: Files don't allow children:
    allows_children = Bool(False)

    #: Description of what the demo does:
    description = HTML()

    #: The base URL for links:
    base_url = Property(observe='path')

    #: The css file for this node.
    css_filename = Str("default.css")

    #: Log of all print messages displayed:
    log = Code()

    _nice_name = Str()

    def init(self):
        self.log = ""

    # -------------------------------------------------------------------------
    #  Implementation of the 'path' property:
    # -------------------------------------------------------------------------

    def _get_path(self):
        return join(self.parent.path, self.name)

    def _get_base_url(self):
        if isdir(self.path):
            base_dir = self.path
        else:
            base_dir = dirname(self.path)
        return base_dir

    # -------------------------------------------------------------------------
    #  Implementation of the 'nice_name' property:
    # -------------------------------------------------------------------------

    def _get_nice_name(self):
        if not self._nice_name:
            name, ext = splitext(self.name)
            self._nice_name = user_name_for(name)
        return self._nice_name

    def _set_nice_name(self, value):
        old = self.nice_name
        self._nice_name = value
        self.trait_property_changed("nice_name", old, value)

    # -------------------------------------------------------------------------
    #  Returns whether or not the object has children:
    # -------------------------------------------------------------------------

    def has_children(self):
        """Returns whether or not the object has children."""
        return False

    def get_children(self):
        """Gets the demo file's children."""
        return []


class DemoFile(DemoFileBase):

    #: Source code for the demo:
    source = Code()

    #: Demo object whose traits UI is to be displayed:
    demo = Instance(HasTraits)

    #: Local namespace for executed code:
    locals = Dict(Str, Any)

    def init(self):
        super().init()
        description, source = parse_source(self.path)
        self.description = publish_html_str(description, self.css_filename)
        self.source = source
        self.run_code()

    def run_code(self):
        """Runs the code associated with this demo file."""
        try:
            # Get the execution context dictionary:
            locals = self.parent.init_dic
            locals["__name__"] = "___main___"
            locals["__file__"] = self.path
            sys.modules["__main__"].__file__ = self.path

            exec(self.source, locals, locals)

            demo = self._get_object("modal_popup", locals)
            if demo is not None:
                demo = ModalDemoButton(demo=demo)
            else:
                demo = self._get_object("popup", locals)
                if demo is not None:
                    demo = DemoButton(demo=demo)
                else:
                    demo = self._get_object("demo", locals)
        except Exception:
            traceback.print_exc()
        else:
            self.demo = demo
        self.locals = locals

    # -------------------------------------------------------------------------
    #  Get a specified object from the execution dictionary:
    # -------------------------------------------------------------------------

    def _get_object(self, name, dic):
        object = dic.get(name) or dic.get(name.capitalize())
        if object is not None:
            if isinstance(type(object), type):
                try:
                    object = object()
                except Exception:
                    pass

            if isinstance(object, HasTraits):
                return object

        return None


# HTML template for displaying an image file:
_image_template = """<html>
<head>
<link rel="stylesheet" type="text/css" href="{}">
</head>
<body>
<img src="{}">
</body>
</html>
"""


class DemoContentFile(DemoFileBase):
    def init(self):
        super().init()
        file_str = _read_file(self.path)
        self.description = publish_html_str(file_str, self.css_filename)


class DemoImageFile(DemoFileBase):
    def init(self):
        super().init()
        self.description = _image_template.format(self.css_filename, self.path)


class DemoPath(DemoTreeNodeObject):
    """This class represents a directory."""

    # -------------------------------------------------------------------------
    #  Trait definitions:
    # -------------------------------------------------------------------------

    #: Parent of this package:
    parent = Any()

    #: Name of file system path to this package:
    path = Property(observe='parent.path,name')

    #: Description of what the demo does:
    description = Property(HTML, observe="path,css_filename")

    #: The base URL for links:
    base_url = Property(observe='path')

    #: The css file for this node.
    css_filename = Str("default.css")

    #: Name of the directory:
    name = Str()

    #: UI form of the 'name':
    nice_name = Property()

    #: Dictionary containing symbols defined by the path's '__init__.py' file:
    init_dic = Property()

    #: Should .py files be included?
    use_files = Bool(True)

    #: Paths do allow children:
    allows_children = Bool(True)

    #: Configuration dictionary for this node
    #: This trait is set when a config file exists for the parent of this path.
    config_dict = Dict()

    #: Configuration file for this node.
    config_filename = Str()

    #: The css file for this node.
    css_filename = Str("default.css")

    #: Shadow trait for description property
    _description = Str()

    #: Cached value of the nice_name property.
    _nice_name = Str()

    #: Dictionary mapping file extensions to callables
    _file_factory = Dict()

    def __file_factory_default(self):
        return {
            ".htm": DemoContentFile,
            ".html": DemoContentFile,
            ".jpeg": DemoImageFile,
            ".jpg": DemoImageFile,
            ".png": DemoImageFile,
            ".py": DemoFile,
            ".rst": DemoContentFile,
            ".txt": DemoContentFile,
        }

    # -------------------------------------------------------------------------
    #  Implementation of the 'path' property:
    # -------------------------------------------------------------------------

    def _get_path(self):
        if self.parent is not None:
            path = join(self.parent.path, self.name)
        else:
            path = self.name

        return path

    def _get_base_url(self):
        if isdir(self.path):
            base_dir = self.path
        else:
            base_dir = dirname(self.path)
        return base_dir

    # -------------------------------------------------------------------------
    #  Implementation of the 'nice_name' property:
    # -------------------------------------------------------------------------

    def _get_nice_name(self):
        if not self._nice_name:
            self._nice_name = user_name_for(self.name)
        return self._nice_name

    # -------------------------------------------------------------------------
    #  Setter for the 'nice_name' property:
    # -------------------------------------------------------------------------

    def _set_nice_name(self, value):
        old = self.nice_name
        self._nice_name = value
        self.trait_property_changed("nice_name", old, value)

    # -------------------------------------------------------------------------
    #  Implementation of the 'description' property:
    # -------------------------------------------------------------------------

    @cached_property
    def _get_description(self):
        index_rst = os.path.join(self.path, DESCRIPTION_RST_FILENAME)
        if os.path.exists(index_rst):
            with open(index_rst, "r", encoding="utf-8") as f:
                description = f.read()
        else:
            description = ""

        if self.css_filename:
            result = publish_html_str(description, self.css_filename)
        else:
            result = publish_html_str(description)
        return result

    # -------------------------------------------------------------------------
    #  Implementation of the 'init_dic' property:
    # -------------------------------------------------------------------------

    def _get_init_dic(self):
        init_dic = {}
        description, source = parse_source(join(self.path, "__init__.py"))
        exec((exec_str + source), init_dic)
        return init_dic

    # -------------------------------------------------------------------------
    #  Returns whether or not the object has children:
    # -------------------------------------------------------------------------

    def has_children(self):
        """Returns whether or not the object has children."""
        path = self.path
        for name in listdir(path):
            cur_path = join(path, name)
            if isdir(cur_path):
                return True

            if self.use_files:
                name, ext = splitext(name)
                if (ext == ".py") and (name != "__init__"):
                    return True
                elif ext in self._file_factory:
                    return True

        return False

    # -------------------------------------------------------------------------
    #  Gets the object's children:
    # -------------------------------------------------------------------------

    def get_children(self):
        """Gets the object's children."""
        if self.config_dict or self.config_filename:
            children = self.get_children_from_config()
        else:
            children = self.get_children_from_datastructure()
        return children

    # -------------------------------------------------------------------------
    #  Gets the object's children based on the filesystem structure.
    # -------------------------------------------------------------------------
    def get_children_from_datastructure(self):
        """Gets the object's children based on the filesystem structure."""

        dirs = []
        files = []
        path = self.path
        for name in listdir(path):
            cur_path = join(path, name)
            if isdir(cur_path):
                if self.has_py_files(cur_path):
                    dirs.append(
                        DemoPath(
                            parent=self,
                            name=name,
                            css_filename=join('..', self.css_filename),
                        )
                    )
            elif self.use_files:
                if name != "__init__.py":
                    try:
                        demo_file = self._handle_file(name)
                        demo_file.css_filename = self.css_filename
                        files.append(demo_file)
                    except KeyError:
                        pass

        sort_key = operator.attrgetter("name")
        dirs.sort(key=sort_key)
        files.sort(key=sort_key)

        return dirs + files

    # -------------------------------------------------------------------------
    # Gets the object's children as specified in its configuration file or
    # dictionary.
    # -------------------------------------------------------------------------

    def get_children_from_config(self):
        """
        Gets the object's children as specified in its configuration file or
        dictionary.
        """

        if not self.config_dict:
            if exists(self.config_filename):
                try:
                    self.config_dict = ConfigObj(self.config_filename)
                except Exception:
                    pass
        if not self.config_dict:
            return self.get_children_from_datastructure()

        dirs = []
        files = []
        for keyword, value in self.config_dict.items():
            if not value.get("no_demo"):
                sourcedir = value.pop("sourcedir", None)
                if sourcedir is not None:
                    # This is a demo directory.
                    demoobj = DemoPath(
                        parent=self,
                        name=sourcedir,
                        css_filename=join("..", self.css_filename),
                    )
                    demoobj.nice_name = keyword
                    demoobj.config_dict = value
                    dirs.append(demoobj)
                else:
                    names = []
                    filenames = value.pop("files", [])
                    if not isinstance(filenames, list):
                        filenames = [filenames]
                    for filename in filenames:
                        filename = join(self.path, filename)
                        for name in glob.iglob(filename):
                            if basename(name) != "__init__.py":
                                names.append(name)
                    if len(names) > 1:
                        config_dict = {}
                        for name in names:
                            config_dict[basename(name)] = {"files": name}
                        demoobj = DemoPath(parent=self, name="")
                        demoobj.nice_name = keyword
                        demoobj.config_dict = config_dict
                        demoobj.css_filename = os.path.join(
                            "..", self.css_filename
                        )
                        dirs.append(demoobj)
                    elif len(names) == 1:
                        try:
                            demo_file = self._handle_file(name)
                            files.append(demo_file)
                            demo_file.css_filename = self.css_filename
                        except KeyError:
                            pass

        sort_key = operator.attrgetter("nice_name")
        dirs.sort(key=sort_key)
        files.sort(key=sort_key)

        return dirs + files

    # -------------------------------------------------------------------------
    #  Returns whether the specified path contains any .py files:
    # -------------------------------------------------------------------------

    def has_py_files(self, path):
        for name in listdir(path):
            cur_path = join(path, name)
            if isdir(cur_path):
                if self.has_py_files(cur_path):
                    return True

            else:
                name, ext = splitext(name)
                if ext == ".py":
                    return True

        return False

    def _handle_file(self, filename):
        """Process a file based on its extension."""
        _, ext = splitext(filename)
        file_factory = self._file_factory[ext]
        demo_file = file_factory(parent=self, name=filename)
        return demo_file


# -------------------------------------------------------------------------
#  Defines the demo tree editor:
# -------------------------------------------------------------------------

demo_path_view = View(
    UItem(
        "description",
        style="readonly",
        editor=HTMLEditor(
            format_text=True,
            base_url_name='base_url',
        ),
    ),
    id="demo_path_view",
    kind='subpanel',
)

demo_file_view = View(
    HSplit(
        UItem(
            "description",
            style="readonly",
            editor=HTMLEditor(
                format_text=True,
                base_url_name='base_url',
            ),
        ),
        VSplit(
            VGroup(
                UItem("source", style="custom"),
                HGroup(
                    spring,
                    UItem(
                        "handler.run_button",
                    ),
                    visible_when="source is not None",
                ),
            ),
            Tabbed(
                Item(
                    "log",
                    style="readonly",
                    editor=CodeEditor(
                        show_line_numbers=False, selected_color=0xFFFFFF
                    ),
                    label="Output",
                    show_label=False,
                ),
                Item(
                    "locals",
                    editor=ShellEditor(share=True),
                    label="Shell",
                    show_label=False,
                ),
                UItem(
                    "demo",
                    style="custom",
                    resizable=True,
                ),
            ),
            dock="horizontal",
        ),
    ),
    id="demo_file_view",
    handler=demo_file_handler,
    kind='subpanel',
)

demo_content_view = View(
    Tabbed(
        UItem(
            "description",
            style="readonly",
            editor=HTMLEditor(
                format_text=True,
                base_url_name='base_url',
            ),
        ),
    ),
    handler=demo_file_handler,
    kind='subpanel',
)


demo_tree_editor = TreeEditor(
    nodes=[
        ObjectTreeNode(
            node_for=[DemoPath],
            label="nice_name",
            view=demo_path_view,
        ),
        ObjectTreeNode(
            node_for=[DemoFile], label="nice_name", view=demo_file_view
        ),
        ObjectTreeNode(
            node_for=[DemoContentFile],
            label="nice_name",
            view=demo_content_view,
        ),
        ObjectTreeNode(
            node_for=[DemoImageFile], label="nice_name", view=demo_content_view
        ),
    ],
    selected='selected_node',
)


next_tool = Action(
    name='Next',
    image=ImageResource("next"),
    tooltip="Go to next file",
    action="do_next",
    enabled_when="_next_node is not None",
)

previous_tool = Action(
    name='Previous',
    image=ImageResource("previous"),
    tooltip="Go to next file",
    action="do_previous",
    enabled_when="_previous_node is not None",
)

parent_tool = Action(
    name='Parent',
    image=ImageResource("parent"),
    tooltip="Go to next file",
    action="do_parent",
    enabled_when="(selected_node is not None) and "
    "(object.selected_node.parent is not None)",
)


class Demo(ModelView):

    #: Root path object for locating demo files:
    model = Instance(DemoPath)

    #: Path to the root demo directory:
    path = Str()

    #: Selected node of the demo path tree.
    selected_node = Any()

    #: Title for the demo
    title = Str()

    _next_node = Property()

    _previous_node = Property()

    def do_next(self, event=None):
        self.selected_node = self._next_node

    def do_previous(self, event=None):
        self.selected_node = self._previous_node

    def do_parent(self, event=None):
        if self.selected_node is not None:
            parent = self.selected_node.parent
            self.selected_node = parent

    def init(self, info):
        info.ui.title = self.title
        return True

    def _get__next_node(self):
        next = None
        node = self.selected_node
        children = node.tno_get_children(node)

        if len(children) > 0:
            next = children[0]
        else:
            parent = node.parent
            while parent is not None:
                siblings = parent.tno_get_children(parent)
                index = siblings.index(node)
                if index < (len(siblings) - 1):
                    next = siblings[index + 1]
                    break

                parent, node = parent.parent, parent

        return next

    def _get__previous_node(self):
        previous = None
        node = self.selected_node
        parent = node.parent
        if parent is not None:
            siblings = parent.tno_get_children(parent)
            index = siblings.index(node)
            if index > 0:
                previous = siblings[index - 1]
                previous_children = previous.tno_get_children(previous)
                while len(previous_children) > 0:
                    previous = previous_children[-1]
                    previous_children = previous.tno_get_children(previous)
            else:
                previous = parent

        return previous

    # -------------------------------------------------------------------------
    #  Traits view definitions:
    # -------------------------------------------------------------------------

    def default_traits_view(self):
        # XXX need to do this to hide the instantiation of ToolBar from null
        # toolkit tests.  It would be preferable to have this be declarative.
        return View(
            Item(
                name="model",
                id="model",
                show_label=False,
                editor=demo_tree_editor,
            ),
            id="traitsui.demos.demo.Demo",
            toolbar=ToolBar(
                previous_tool, parent_tool, next_tool, show_tool_names=True
            ),
            resizable=True,
            width=1200,
            height=700,
        )


# -------------------------------------------------------------------------
#  Utilities to convert rst strings/files to html.
# -------------------------------------------------------------------------


def _get_settings(css_path=None):
    """Helper function to make settings dictionary
    consumable by docutils

    Parameters
    ----------
    css_path: string or None (default)
        If not None, use the CSS stylesheet.

    Returns
    -------
    dict
    """
    settings = {'output_encoding': 'unicode'}
    if css_path is not None:
        settings['stylesheet_path'] = css_path
        settings['embed_stylesheet'] = False
        settings['stylesheet'] = None

    return settings


def publish_html_str(rst_str, css_path=None):
    """Format RST string to html using `docutils` if available.
    Otherwise, return the input `rst_str`.

    Parameters
    ----------
    rst_str: string
        reStructuredText

    css_path: string or None (default)
        If not None, use the CSS stylesheet.

    Returns
    -------
    string
    """
    try:
        from docutils.core import publish_string
    except Exception:
        return rst_str

    settings = _get_settings(css_path)
    return publish_string(
        rst_str, writer_name='html', settings_overrides=settings
    )


def publish_html_file(rst_file_path, html_out_path, css_path=None):
    """Format reStructuredText in `rst_file_path` to html using `docutils`
    if available. Otherwise, does nothing.

    Parameters
    ----------
    rst_file_path: string

    html_out_path: string

    css_path: string or None (default)
        If not None, use the CSS stylesheet.

    Returns
    -------
    None
    """
    try:
        from docutils.core import publish_file
    except Exception:
        return

    settings = _get_settings(css_path)
    publish_file(
        source_path=rst_file_path,
        destination_path=html_out_path,
        writer_name='html',
        settings_overrides=settings,
    )


# -------------------------------------------------------------------------
#  Function to run the demo:
# -------------------------------------------------------------------------


def demo(
    use_files=False,
    dir_name=None,
    config_filename="",
    title="Traits UI Demos",
    css_filename="default.css",
):
    if dir_name is None:
        dir_name = dirname(abspath(sys.argv[0]))
    path, name = split(dir_name)
    if len(config_filename) > 0 and not isabs(config_filename):
        config_filename = join(path, name, config_filename)
    Demo(
        path=path,
        title=title,
        model=DemoPath(
            name=dir_name,
            nice_name=user_name_for(name),
            use_files=use_files,
            config_filename=config_filename,
            css_filename=css_filename,
        ),
    ).configure_traits()