SetupDocs-1.0.5/0000755000175100001440000000000011456206774013163 5ustar ischnellusersSetupDocs-1.0.5/LICENSE.txt0000644000175100001440000000312011455424502014770 0ustar ischnellusersThis software is OSI Certified Open Source Software. OSI Certified is a certification mark of the Open Source Initiative. Copyright (c) 2006, Enthought, Inc. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Enthought, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. SetupDocs-1.0.5/SetupDocs.egg-info/0000755000175100001440000000000011456206774016566 5ustar ischnellusersSetupDocs-1.0.5/SetupDocs.egg-info/entry_points.txt0000644000175100001440000000105411456206774022064 0ustar ischnellusers[distutils.setup_keywords] docs_in_egg_location = setupdocs.setupdocs:check_string ssh_username = setupdocs.setupdocs:check_string html_doc_repo = setupdocs.setupdocs:check_string docs_in_egg = setupdocs.setupdocs:check_bool docs_dest = setupdocs.setupdocs:check_string docs_source = setupdocs.setupdocs:check_string ssh_remote_dir = setupdocs.setupdocs:check_string ssh_server = setupdocs.setupdocs:check_string [distutils.commands] build_docs = setupdocs.setupdocs:BuildDocs clean = setupdocs.setupdocs:MyClean dist_docs = setupdocs.setupdocs:DistDocs SetupDocs-1.0.5/SetupDocs.egg-info/SOURCES.txt0000644000175100001440000000043611456206774020455 0ustar ischnellusersLICENSE.txt README.txt setup.cfg setup.py SetupDocs.egg-info/PKG-INFO SetupDocs.egg-info/SOURCES.txt SetupDocs.egg-info/dependency_links.txt SetupDocs.egg-info/entry_points.txt SetupDocs.egg-info/requires.txt SetupDocs.egg-info/top_level.txt setupdocs/__init__.py setupdocs/setupdocs.pySetupDocs-1.0.5/SetupDocs.egg-info/top_level.txt0000644000175100001440000000001211456206774021311 0ustar ischnelluserssetupdocs SetupDocs-1.0.5/SetupDocs.egg-info/dependency_links.txt0000644000175100001440000000000111456206774022634 0ustar ischnellusers SetupDocs-1.0.5/SetupDocs.egg-info/PKG-INFO0000644000175100001440000000101511456206774017660 0ustar ischnellusersMetadata-Version: 1.0 Name: SetupDocs Version: 1.0.5 Summary: setuptools plugin that automates building of docs from ReST source Home-page: UNKNOWN Author: Enthought, Inc. Author-email: info@enthought.com License: UNKNOWN Description: UNKNOWN Platform: UNKNOWN Classifier: License :: OSI Approved :: BSD License Classifier: Operating System :: MacOS Classifier: Operating System :: Microsoft :: Windows Classifier: Operating System :: OS Independent Classifier: Operating System :: POSIX Classifier: Operating System :: Unix SetupDocs-1.0.5/SetupDocs.egg-info/requires.txt0000644000175100001440000000001311456206774021160 0ustar ischnellusers [nonets] SetupDocs-1.0.5/PKG-INFO0000644000175100001440000000101511456206774014255 0ustar ischnellusersMetadata-Version: 1.0 Name: SetupDocs Version: 1.0.5 Summary: setuptools plugin that automates building of docs from ReST source Home-page: UNKNOWN Author: Enthought, Inc. Author-email: info@enthought.com License: UNKNOWN Description: UNKNOWN Platform: UNKNOWN Classifier: License :: OSI Approved :: BSD License Classifier: Operating System :: MacOS Classifier: Operating System :: Microsoft :: Windows Classifier: Operating System :: OS Independent Classifier: Operating System :: POSIX Classifier: Operating System :: Unix SetupDocs-1.0.5/setup.py0000644000175100001440000000445011456155234014672 0ustar ischnellusers#!/usr/bin/env python # # Copyright (c) 2008-2010 by Enthought, Inc. # All rights reserved. """ Adds additional setup.py commands to support building Sphinx docs. Having this package installed adds the following commands to setup.py: build_docs: Builds documentation in various formats in a ./build/docs subdirectory if Sphinx is available. dist_docs: Builds a distribution file for the html docs in ./dist. The '-c' option will overwrite the existing ./docs/html.zip with the generated distribution file and check it in for you. The '-u' option will build both html and pdf doc distributions, check them in for you, and publish the docs to a website. See the docs inside this project for more information. """ from setuptools import setup, find_packages setup( author = "Enthought, Inc.", author_email = 'info@enthought.com', classifiers = [c.strip() for c in """\ License :: OSI Approved :: BSD License Operating System :: MacOS Operating System :: Microsoft :: Windows Operating System :: OS Independent Operating System :: POSIX Operating System :: Unix """.splitlines() if len(c.strip()) > 0], description = 'setuptools plugin that automates building of docs from ' 'ReST source', entry_points = { 'distutils.commands': [ 'build_docs = setupdocs.setupdocs:BuildDocs', 'dist_docs = setupdocs.setupdocs:DistDocs', 'clean = setupdocs.setupdocs:MyClean' ], 'distutils.setup_keywords': [ 'docs_source = setupdocs.setupdocs:check_string', 'docs_dest = setupdocs.setupdocs:check_string', 'docs_in_egg = setupdocs.setupdocs:check_bool', 'docs_in_egg_location = setupdocs.setupdocs:check_string', 'html_doc_repo = setupdocs.setupdocs:check_string', 'ssh_server = setupdocs.setupdocs:check_string', 'ssh_username = setupdocs.setupdocs:check_string', 'ssh_remote_dir = setupdocs.setupdocs:check_string' ], }, extras_require = { # Non-ETS dependencies must be in a special extra. 'nonets': [ ], }, name = 'SetupDocs', packages = find_packages(), version = "1.0.5", ) SetupDocs-1.0.5/README.txt0000644000175100001440000000161511455424502014652 0ustar ischnellusersSetupdocs is a setuptools extension that help doc building automation. It adds two commands to the setup.py command. build_docs ---------- Finds Sphinx source in docs/ and buils html. Can also build latex and pdf with --formats= directive if latex is installed. dist_docs --------- Builds html docs and creates an html.zip in the dist/ folder. With -c, replaces the html.zip in the docs folder and checks it in. With -u, it doesn't create the html.zip but instead updates the docs on the website. It does this by 1) getting a fresh svn checkout of the docs, 2) building the docs with Sphinx and overwriting the old ones, 3) svn adding and checking in the new and changed docs, 4) ssh login to www, 5) cd to the doc dir, 6) svn up and chmod g+w. It's not perfect, but it pretty much works. Some options can be configured in setup.py, and are in Mayavi and Chaco. Command-line help is available via -h. SetupDocs-1.0.5/setup.cfg0000644000175100001440000000031111456206774014777 0ustar ischnellusers[egg_info] tag_build = tag_date = 0 tag_svn_revision = 0 [nosetests] verbosity = 0 detailed-errors = 1 with-coverage = 1 with-doctest = 1 [aliases] release = egg_info -RDb '' bdist_egg = bdist_egg SetupDocs-1.0.5/setupdocs/0000755000175100001440000000000011456206774015174 5ustar ischnellusersSetupDocs-1.0.5/setupdocs/__init__.py0000644000175100001440000000000011455424502017261 0ustar ischnellusersSetupDocs-1.0.5/setupdocs/setupdocs.py0000644000175100001440000004132211456156725017561 0ustar ischnellusers#!/usr/bin/env python # # Copyright (c) 2008-2009 by Enthought, Inc. # All rights reserved. import os, sys import shutil import subprocess import zipfile from distutils import log from distutils.command.clean import clean from distutils.errors import DistutilsSetupError from setuptools import Command DOC_DIR = os.path.join(os.path.abspath(os.getcwd()), 'docs') SOURCE_DIR = os.path.join(DOC_DIR, 'source') ZIP_FILE_NAME = 'html.zip' HTML_ZIP = os.path.join(DOC_DIR, ZIP_FILE_NAME) BUILD_DIR = os.path.join(os.path.abspath(os.getcwd()), 'build') TARGET_DIR = os.path.join(BUILD_DIR, 'docs') def is_sphinx_installed(): """ Check to see if Sphinx is installed (based on a simple import). """ required_sphinx_version = "0.4.2" try: import sphinx # FIXME: Once verlib is in the stdlib, use verlib's comparison if sphinx.__version__ < "required_sphinx_version": log.warn('Sphinx install of version >=%s could not be verified.' % required_sphinx_version) return True except ImportError: return False def create_html_zip(target, commit): """Create html_docs.zip in target directory. This is useful if the rst source files have recently been updated and a new zipped html file needs to be created for distribution. If commit is 1, html_docs.zip will replace the existing file in docs/ and be checked in to svn. This will only work if the user has commit access to svn.enthought.com/enthought. """ html_source = os.path.join(TARGET_DIR, 'html') target_file = os.path.join(target, ZIP_FILE_NAME) if not os.path.exists(target): os.makedirs(target) if os.path.exists(target_file): os.remove(target_file) # ZIP_DEFLATED actually compresses the archive. However, there will be a # RuntimeError if zlib is not installed, so we check for it. ZIP_STORED # produces an uncompressed zip, but does not require zlib. try: zf = zipfile.ZipFile(target_file, 'w', compression=zipfile.ZIP_DEFLATED) except RuntimeError: zf = zipfile.ZipFile(target_file, 'w', compression=zipfile.ZIP_STORED) # "Subract" the root of the path to a file so that only the part of the # path necessary for the archive is left. Was originally in make_docs.py. # There may be a better way, but this works. length = len(os.path.abspath(html_source)) subtract_base = lambda root: root[length+1:] for root, dirs, files in os.walk(html_source): baseless = subtract_base(root) if not '.doctrees' in baseless.split(os.sep): for f in files: zf.write(os.path.join(root, f), os.path.join('html', baseless, f)) zf.close() log.info("%s now ready." % target_file) if commit == 1: message = "Updating html docs zip file." subprocess.call(['svn', 'ci', zf.filename, '-m', message]) # subprocess.call(['svn', 'st'])#, zf.filename]) def unzip_html_docs(src_path, dest_dir): """ Given a path to a zipfile, extract its contents to a given 'dest_dir'. """ if not os.path.isfile(src_path): print "Warning: source %r does not exist" % src_path return file = zipfile.ZipFile(src_path) for name in file.namelist(): cur_name = os.path.join(dest_dir, name) cur_name = cur_name.replace('/', os.sep) if not os.path.exists(os.path.dirname(cur_name)): os.makedirs(os.path.dirname(cur_name)) if not name.endswith('/'): out = open(cur_name, 'wb') out.write(file.read(name)) out.flush() out.close() file.close() def show_formats(): DOC_FORMATS = { 'html': (BuildDocs, [], "(default) create folder 'build/docs/html' " "with html documentation"), 'latex': (BuildDocs, [], "create folder 'build/docs/latex' with latex " "source files "), 'pdf': (BuildDocs, [], "make pdf file from generated latex in " "'build/docs/latex'. requires latex install with pdflatex command"), 'html,latex,...': (None, [], "generate more than one format"), 'all': (BuildDocs, [], "build html, latex, and pdf") } from distutils.fancy_getopt import FancyGetopt formats = [] for format in DOC_FORMATS.keys(): formats.append(("formats=" + format, None, DOC_FORMATS[format][2])) formats.sort() pretty_printer = FancyGetopt(formats) pretty_printer.print_help("Available doc formats:") def get_source_dirs(doc_dir): source_dirs = [] for root, dirnames, filenames in os.walk(doc_dir): if 'conf.py' in filenames: source_dirs.append(os.path.abspath(root)) log.info('Using source directory %s' % root) return source_dirs def list_docs_data_files(build_docs_loc, docs_location): """ List the files to add to a project by inspecting the documentation directory. This works only if called after the build step, as the files have to be built. returns a list of (install_dir, [data_files, ]) tuples. """ if docs_location is None: docs_location = 'docs' return_list = [] for root, dirs, files in os.walk(build_docs_loc, topdown=True): # Modify inplace the list of directories to walk dirs[:] = [d for d in dirs if not d.startswith('.')] if len(files) == 0: continue install_dir = root.replace(build_docs_loc, docs_location) return_list.append( (install_dir, [os.path.join(root, f) for f in files])) return return_list class BuildDocs(Command): description = "Build documentation from restructured text sources." user_options = [ ('formats=', None, 'documentation formats to generate (comma-separated ' 'list)'), ] help_options = [ ('help-formats', None, 'list available documentation formats', show_formats), ] def run(self): if is_sphinx_installed(): from sphinx.application import Sphinx from sphinx.util.console import nocolor # Windows' poor cmd box doesn't understand ANSI sequences if not sys.stdout.isatty() or sys.platform == 'win32': nocolor() # Check to see if version information is provided in setup.py # If it is, it will override version information in conf.py. conf_overrides = {} version = self.distribution.get_version() if version != "0.0.0": conf_overrides['version'] = version conf_overrides['release'] = version for i in range(len(self.source_dirs)): for format in self.formats: try: builder_target = os.path.join(self.target_dir, format, self.projects[i]) doctree_dir = os.path.join(builder_target, '.doctrees') self.mkpath(doctree_dir) # The sphinx interface requires 7 arguments: sourcedir, # confdir, outdir, doctreedir, buildername, # confoverrides, and status app = Sphinx(self.source_dirs[i], self.source_dirs[i], builder_target, doctree_dir, format, conf_overrides, self.status_stream ) app.builder.build_update() if self.pdf_build and format == 'latex': try: os.chdir(builder_target) subprocess.call(["make", "all-pdf"]) log.info("PDF doc created in %s." % builder_target) except Exception, e: log.error(e) except IOError, e: log.warn(e) except Exception, e: log.error('Unable to generate %s docs.' % format) if format == 'html' and len(self.formats) == 1: log.info("Installing %s html documentation from zip" " file.\n" % self.distribution.get_name()) unzip_html_docs(HTML_ZIP, TARGET_DIR) else: if 'html' not in self.formats: log.error("Sphinx must be installed for RST doc conversion.") elif len(self.formats) > 1: # Unzip the docs into the 'html' folder. log.info("Installing %s html documentation from zip file. Cannot" " generate other formats without Sphinx install.\n" % self.name) unzip_html_docs(HTML_ZIP, TARGET_DIR) else: # Unzip the docs into the 'html' folder. log.info("Installing %s html documentation from zip file.\n" % self.name) unzip_html_docs(HTML_ZIP, TARGET_DIR) # Using extend so the existing data_files doesn't get replaced if self.distribution.docs_in_egg: # This check is needed because of a setuptools or (numpy?) distutils bug that # is causing the easy_install process to stop adding subpackages. This may be # because setupdocs is being required by multiple packages in a dependency # chain; but really, who knows. if not self.distribution.data_files: self.distribution.data_files = [] if self.distribution.docs_in_egg_location is None: doc_files = list_docs_data_files(self.target_dir, self.distribution.docs_dest) else: doc_files = list_docs_data_files(self.target_dir, self.distribution.docs_in_egg_location) self.distribution.data_files.extend(doc_files) def initialize_options (self): self.formats = None self.check = 0 self.pdf_build = False self.source_dirs = None def finalize_options (self): self.name = self.distribution.get_name() self.ensure_string_list('formats') if self.formats == ['all']: self.formats = ['html', 'latex'] self.pdf_build = True if self.formats is None: self.formats = ['html'] if 'pdf' in self.formats: self.formats.remove('pdf') if 'latex' not in self.formats: self.formats.append('latex') self.pdf_build = True if self.source_dirs is None: if getattr(self.distribution, 'docs_source', None) is None: self.source_dirs = get_source_dirs(DOC_DIR) else: self.source_dirs = get_source_dirs(self.distribution.docs_source) if getattr(self.distribution, 'docs_dest', None) is None: self.target_dir = TARGET_DIR else: self.target_dir = os.path.join(BUILD_DIR, self.distribution.docs_dest) # This looks to see if there are multiple directories under docs/source self.projects = [] for source in self.source_dirs: project = source.split(os.sep)[-1] if project != 'source': self.projects.append(project) else: self.projects = [''] self.status_stream = sys.stdout class DistDocs(Command): description = "create a zip file of the html documentation" user_options = [ ('dist-dir=', 'd', 'specify directory for zip output'), ('checkin', 'c', 'replace existing zip file and checkin to svn (only ' 'works if you have commit access)'), ('update', 'u', 'update the docs on the code.enthought.com website'), ('repo=', 'r', 'repository where web docs will be checked out and ' 'updated (default set in setup.cfg)'), ('ssh-server=', 's', 'server to log into when updating remote docs ' ' (default set in setup.cfg)'), ('remote-dir=', 't', 'location of docs on remote server ' ' (default set in setup.cfg)'), ('username=', None, 'username to specify for ssh login when updating ' 'CEC'), ] boolean_options = ['checkin', 'update'] def run(self): if not is_sphinx_installed(): log.error("Sphinx must be installed to build the docs for the " "zip-file.") else: try: if self.update == 1: self.update_docs() else: self.run_command('build_docs') create_html_zip(self.dist_dir, self.checkin) except Exception, e: log.error(e) def update_docs(self): checkout_dir = os.path.join(os.path.abspath(os.path.dirname(__file__)), TARGET_DIR) print self.repo if os.path.exists(checkout_dir): shutil.rmtree(checkout_dir) try: log.info("Getting fresh checkout from repository...") co_retcode = subprocess.call(['svn', 'co', self.repo, checkout_dir, '-q']) if co_retcode != 0: raise RuntimeError("subversion checkout failed.") except Exception, e: log.error(e) return self.reinitialize_command('build_docs', formats='all') self.run_command('build_docs') # Removed everything from the latex directory except the PDF, which # we want to check in. for root, dirs, files in os.walk(checkout_dir): # We don't want to remove the .svn directories, either. if '.svn' in root: continue for file in files: if 'latex' in root and not file.endswith('.pdf'): os.remove(os.path.join(root, file)) st_proc = subprocess.Popen(['svn', 'st', checkout_dir], stdout=subprocess.PIPE, stderr=subprocess.PIPE) st_proc.wait() st_out = st_proc.communicate()[0].split('\n') for st_message in st_out: if '.doctrees' not in st_message and st_message.startswith('?'): subprocess.call(['svn', 'add', st_message.split()[1]]) try: ci_proc = subprocess.call(['svn', 'ci', checkout_dir, '-m', 'Checking in html docs from setup.py command']) if ci_proc != 0: raise RuntimeError("Unable to perform svn commit.") except Exception, e: log.error(e) if self.username is None: self.username = raw_input("Please enter username for ssh access: ") try: ssh_proc = subprocess.call('ssh %s@%s " \ cd %s \ && svn up \ && chmod -R g+w * \ && chgrp -R apache *"' % (self.username, self.ssh_server, self.remote_dir), shell=True) if ssh_proc != 0: raise RuntimeError("Update via ssh failed.") else: log.info("Website docs updated.") except: log.error("Unable to update the website via ssh.") def initialize_options(self): self.dist_dir = None self.checkin = 0 self.update = 0 self.username = None self.repo = None self.ssh_server = None self.remote_dir = None def finalize_options(self): if self.dist_dir is None: self.dist_dir = 'dist' if self.checkin: self.dist_dir = 'docs' if self.username is None: self.username = self.distribution.ssh_username if self.repo is None: self.repo = self.distribution.html_doc_repo if self.ssh_server is None: self.ssh_server = self.distribution.ssh_server if self.remote_dir is None: self.remote_dir = self.distribution.ssh_remote_dir class MyClean(clean): """ A hook to remove the generated documentation when cleaning. We subclass distutils' clean command because neither numpy.distutils nor setuptools has an implementation. """ def run(self): clean.run(self) if os.path.exists('build/docs'): log.info("Removing '%s' (and everything under it)" % 'build/docs') shutil.rmtree('build/docs') def check_bool(dist, attr, value): """Verify that value is True, False, 0, or 1""" if bool(value) != value: raise DistutilsSetupError( "%r must be a boolean value (got %r)" % (attr, value) ) def check_string(dist, attr, value): if not isinstance(value, basestring): raise DistutilsSetupError("%s must be a string" % attr)