#------------------------------------------------------------------------------ # Copyright (c) 2013-2025, Nucleic Development Team. # # Distributed under the terms of the Modified BSD License. # # The full license is in the file LICENSE, distributed with this software. #------------------------------------------------------------------------------ """ Generate the Example Documentation for the Enaml Examples Run as part of the documentation build script. Requires PyQt4. Look for example enaml files with the line: << autodoc-me >> Generate an rst file, then open the app and take a snapshot. Note: Many examples have dependencies outside of the normal Enaml dependencies. These will need to be installed for the snapshots to be generated. """ from __future__ import print_function import argparse import os import re import shutil import sys from textwrap import dedent from atom.api import Atom, Str, Value import enaml from enaml.qt.qt_application import QtApplication from enaml.qt.QtWidgets import QApplication from enaml.qt.QtTest import QTest class SnapShot(Atom): """ Generate a snapshot of an enaml view. """ #: The snapshot save path. path = Str() #: The enaml view object. view = Value() def _observe_view(self, change): """ Move window and allow it to draw before taking the snapshot. """ if change['type'] == 'create': self.view.initial_position = (10, 10) self.view.always_on_top = True def snapshot(self): """ Take a snapshot of the window and close it. """ widget = self.view.proxy.widget framesize = widget.window().frameSize() screen = QApplication.primaryScreen() screen.grabWindow( QApplication.desktop().winId(), widget.x(), widget.y(), framesize.width(), framesize.height() ).save(self.path) self.view.close() def save_snapshot_of_module(mod, image_path): view = mod.Main() snapshot = SnapShot(path=image_path, view=view) view.show() QTest.qWaitForWindowExposed(view.proxy.widget) QTest.qWait(500) snapshot.snapshot() QTest.qWait(100) def extract_docstring(script_text): """ Extract the docstring from an example Enaml script. """ # The docstring is found between the first two '"""' strings. return script_text.split('"""')[1] def clean_docstring(docstring): """ Convert a docstring into ReStructuredText format. """ docstring = docstring.replace('<< autodoc-me >>\n', '').strip() # Find backquoted identifiers, and double the backquotes to match RST. docstring = re.sub( pattern=r"`(?P[A-Za-z_]+)`", # Backquoted identifiers repl=r"``\g``", # Double backquoted identifiers string=docstring) return docstring SCREENSHOT_RST_TEMPLATE = dedent(""" Screenshot ------------------------------------------------------------------------------- .. image:: images/{name} """) EXAMPLE_DOC_RST_TEMPLATE = dedent(""" .. NOTE: This RST file was generated by `make examples`. Do not edit it directly. See docs/source/examples/example_doc_generator.py {title} Example =============================================================================== {docstring_rst} .. TIP:: To see this example in action, download it from :download:`{name} <../../../{path}>` and run:: $ enaml-run {name}.enaml {screenshot_rst} Example Enaml Code ------------------------------------------------------------------------------- .. literalinclude:: ../../../{path} :language: enaml """) def generate_example_doc(docs_path, script_path): """ Generate an RST and a PNG for an example file. Parameters ---------- docs_path : str Full path to enaml/docs/source/examples script_path : str Full path to the example enaml file """ script_name = os.path.basename(script_path) script_name = script_name[:script_name.find('.')] print('generating doc for %s' % script_name) script_title = script_name.replace('_', ' ').title() script_image_name = 'ex_' + script_name + '.png' image_path = os.path.join(docs_path, 'images', script_image_name) rst_path = os.path.join( docs_path, 'ex_' + script_name + '.rst') relative_script_path = script_path[ script_path.find('examples'):].replace('\\', '/') # Add the script to the Python Path old_python_path = sys.path sys.path = sys.path + [os.path.dirname(script_path)] snapshot_success = False with enaml.imports(): try: mod = __import__(script_name) save_snapshot_of_module(mod, image_path) snapshot_success = True except Exception as err: print('Could not snapshot: %s' % script_name) print(' %s' % err) finally: # The import leaves behind a cache. Clean it up. enaml_cache_dir = os.path.join( os.path.dirname(script_path), '__enamlcache__') if os.path.exists(enaml_cache_dir): shutil.rmtree(enaml_cache_dir) # Restore Python path. sys.path = old_python_path with open(os.path.join(script_path)) as fid: script_text = fid.read() docstring = clean_docstring(extract_docstring(script_text)) screenshot_rst = '' if not snapshot_success else ( SCREENSHOT_RST_TEMPLATE.format(name=script_image_name)) example_doc_rst = EXAMPLE_DOC_RST_TEMPLATE.format( title=script_title, name=script_name, path=relative_script_path, docstring_rst=docstring, screenshot_rst=screenshot_rst) with open(rst_path, 'wb') as rst_output_file: rst_output_file.write(example_doc_rst.lstrip().encode()) def main(white_list): """ Generate documentation for all enaml examples requesting autodoc. Looks in enaml/examples for all enaml files, then looks for the line: << auto-doc >> If the line appears in the script, generate an RST and PNG for the example. """ app = QtApplication() docs_path = os.path.dirname(__file__) base_path = '../../../examples' base_path = os.path.realpath(os.path.join(docs_path, base_path)) # Find all the files in the examples directory with a .enaml extension # that contain the pragma '<< autodoc-me >>', and generate .rst files for # them. for dirname, dirnames, filenames in os.walk(base_path): files = [os.path.join(dirname, f) for f in filenames if f.endswith('.enaml')] if white_list: files = [f for f in files if any([f.endswith(w) for w in white_list])] for fname in files: with open(fname, 'rb') as fid: data = fid.read() if b'<< autodoc-me >>' in data.splitlines(): generate_example_doc(docs_path, fname) if __name__ == '__main__': doc = ("Enaml example documentation generator.\n\n" "By default all examples with the << auto-doc >> directive are " "processed.") parser = argparse.ArgumentParser(description=doc) parser.add_argument('-f', '--filenames', help='Files for which to generate the docs', action='store', nargs='+') args = parser.parse_args() main(args.filenames)