added gh-pages command for GitHub hosted sphinx docs

docs/sphinxext/sphinxtogithub.py

@@ -0,0 +1,381 b''
+#! /usr/bin/env python
+"""
+sphinxtogithub extension Copyright Michael Jones
+
+BSD License
+
+Original at: https://github.com/michaeljones/sphinx-to-github
+"""
+from optparse import OptionParser
+import os
+import sys
+import shutil
+
+
+class DirHelper(object):
+
+    def __init__(self, is_dir, list_dir, walk, rmtree):
+
+        self.is_dir = is_dir
+        self.list_dir = list_dir
+        self.walk = walk
+        self.rmtree = rmtree
+
+class FileSystemHelper(object):
+
+    def __init__(self, open_, path_join, move, exists):
+
+        self.open_ = open_
+        self.path_join = path_join
+        self.move = move
+        self.exists = exists
+
+class Replacer(object):
+    "Encapsulates a simple text replace"
+
+    def __init__(self, from_, to):
+
+        self.from_ = from_
+        self.to = to
+
+    def process(self, text):
+
+        return text.replace( self.from_, self.to )
+
+class FileHandler(object):
+    "Applies a series of replacements the contents of a file inplace"
+
+    def __init__(self, name, replacers, opener):
+
+        self.name = name
+        self.replacers = replacers
+        self.opener = opener
+
+    def process(self):
+
+        text = self.opener(self.name).read()
+
+        for replacer in self.replacers:
+            text = replacer.process( text )
+
+        self.opener(self.name, "w").write(text)
+
+class Remover(object):
+
+    def __init__(self, exists, remove):
+        self.exists = exists
+        self.remove = remove
+
+    def __call__(self, name):
+
+        if self.exists(name):
+            self.remove(name)
+
+class ForceRename(object):
+
+    def __init__(self, renamer, remove):
+
+        self.renamer = renamer
+        self.remove = remove
+
+    def __call__(self, from_, to):
+
+        self.remove(to)
+        self.renamer(from_, to)
+
+class VerboseRename(object):
+
+    def __init__(self, renamer, stream):
+
+        self.renamer = renamer
+        self.stream = stream
+
+    def __call__(self, from_, to):
+
+        self.stream.write(
+                "Renaming directory '%s' -> '%s'\n"
+                    % (os.path.basename(from_), os.path.basename(to))
+                )
+
+        self.renamer(from_, to)
+
+
+class DirectoryHandler(object):
+    "Encapsulates renaming a directory by removing its first character"
+
+    def __init__(self, name, root, renamer):
+
+        self.name = name
+        self.new_name = name[1:]
+        self.root = root + os.sep
+        self.renamer = renamer
+
+    def path(self):
+
+        return os.path.join(self.root, self.name)
+
+    def relative_path(self, directory, filename):
+
+        path = directory.replace(self.root, "", 1)
+        return os.path.join(path, filename)
+
+    def new_relative_path(self, directory, filename):
+
+        path = self.relative_path(directory, filename)
+        return path.replace(self.name, self.new_name, 1)
+
+    def process(self):
+
+        from_ = os.path.join(self.root, self.name)
+        to = os.path.join(self.root, self.new_name)
+        self.renamer(from_, to)
+
+
+class HandlerFactory(object):
+
+    def create_file_handler(self, name, replacers, opener):
+
+        return FileHandler(name, replacers, opener)
+
+    def create_dir_handler(self, name, root, renamer):
+
+        return DirectoryHandler(name, root, renamer)
+
+
+class OperationsFactory(object):
+
+    def create_force_rename(self, renamer, remover):
+
+        return ForceRename(renamer, remover)
+
+    def create_verbose_rename(self, renamer, stream):
+
+        return VerboseRename(renamer, stream)
+
+    def create_replacer(self, from_, to):
+
+        return Replacer(from_, to)
+
+    def create_remover(self, exists, remove):
+
+        return Remover(exists, remove)
+
+
+class Layout(object):
+    """
+    Applies a set of operations which result in the layout
+    of a directory changing
+    """
+
+    def __init__(self, directory_handlers, file_handlers):
+
+        self.directory_handlers = directory_handlers
+        self.file_handlers = file_handlers
+
+    def process(self):
+
+        for handler in self.file_handlers:
+            handler.process()
+
+        for handler in self.directory_handlers:
+            handler.process()
+
+
+class NullLayout(object):
+    """
+    Layout class that does nothing when asked to process
+    """
+    def process(self):
+        pass
+
+class LayoutFactory(object):
+    "Creates a layout object"
+
+    def __init__(self, operations_factory, handler_factory, file_helper, dir_helper, verbose, stream, force):
+
+        self.operations_factory = operations_factory
+        self.handler_factory = handler_factory
+
+        self.file_helper = file_helper
+        self.dir_helper = dir_helper
+
+        self.verbose = verbose
+        self.output_stream = stream
+        self.force = force
+
+    def create_layout(self, path):
+
+        contents = self.dir_helper.list_dir(path)
+
+        renamer = self.file_helper.move
+
+        if self.force:
+            remove = self.operations_factory.create_remover(self.file_helper.exists, self.dir_helper.rmtree)
+            renamer = self.operations_factory.create_force_rename(renamer, remove)
+
+        if self.verbose:
+            renamer = self.operations_factory.create_verbose_rename(renamer, self.output_stream)
+
+        # Build list of directories to process
+        directories = [d for d in contents if self.is_underscore_dir(path, d)]
+        underscore_directories = [
+                self.handler_factory.create_dir_handler(d, path, renamer)
+                    for d in directories
+                ]
+
+        if not underscore_directories:
+            if self.verbose:
+                self.output_stream.write(
+                        "No top level directories starting with an underscore "
+                        "were found in '%s'\n" % path
+                        )
+            return NullLayout()
+
+        # Build list of files that are in those directories
+        replacers = []
+        for handler in underscore_directories:
+            for directory, dirs, files in self.dir_helper.walk(handler.path()):
+                for f in files:
+                    replacers.append(
+                            self.operations_factory.create_replacer(
+                                handler.relative_path(directory, f),
+                                handler.new_relative_path(directory, f)
+                                )
+                            )
+
+        # Build list of handlers to process all files
+        filelist = []
+        for root, dirs, files in self.dir_helper.walk(path):
+            for f in files:
+                if f.endswith(".html"):
+                    filelist.append(
+                            self.handler_factory.create_file_handler(
+                                self.file_helper.path_join(root, f),
+                                replacers,
+                                self.file_helper.open_)
+                            )
+                if f.endswith(".js"):
+                    filelist.append(
+                            self.handler_factory.create_file_handler(
+                                self.file_helper.path_join(root, f),
+                                [self.operations_factory.create_replacer("'_sources/'", "'sources/'")],
+                                self.file_helper.open_
+                                )
+                            )
+
+        return Layout(underscore_directories, filelist)
+
+    def is_underscore_dir(self, path, directory):
+
+        return (self.dir_helper.is_dir(self.file_helper.path_join(path, directory))
+            and directory.startswith("_"))
+
+
+
+def sphinx_extension(app, exception):
+    "Wrapped up as a Sphinx Extension"
+
+    if not app.builder.name in ("html", "dirhtml"):
+        return
+
+    if not app.config.sphinx_to_github:
+        if app.config.sphinx_to_github_verbose:
+            print "Sphinx-to-github: Disabled, doing nothing."
+        return
+
+    if exception:
+        if app.config.sphinx_to_github_verbose:
+            print "Sphinx-to-github: Exception raised in main build, doing nothing."
+        return
+
+    dir_helper = DirHelper(
+            os.path.isdir,
+            os.listdir,
+            os.walk,
+            shutil.rmtree
+            )
+
+    file_helper = FileSystemHelper(
+            open,
+            os.path.join,
+            shutil.move,
+            os.path.exists
+            )
+
+    operations_factory = OperationsFactory()
+    handler_factory = HandlerFactory()
+
+    layout_factory = LayoutFactory(
+            operations_factory,
+            handler_factory,
+            file_helper,
+            dir_helper,
+            app.config.sphinx_to_github_verbose,
+            sys.stdout,
+            force=True
+            )
+
+    layout = layout_factory.create_layout(app.outdir)
+    layout.process()
+
+
+def setup(app):
+    "Setup function for Sphinx Extension"
+
+    app.add_config_value("sphinx_to_github", True, '')
+    app.add_config_value("sphinx_to_github_verbose", True, '')
+
+    app.connect("build-finished", sphinx_extension)
+
+
+def main(args):
+
+    usage = "usage: %prog [options] <html directory>"
+    parser = OptionParser(usage=usage)
+    parser.add_option("-v","--verbose", action="store_true",
+            dest="verbose", default=False, help="Provides verbose output")
+    opts, args = parser.parse_args(args)
+
+    try:
+        path = args[0]
+    except IndexError:
+        sys.stderr.write(
+                "Error - Expecting path to html directory:"
+                "sphinx-to-github <path>\n"
+                )
+        return
+
+    dir_helper = DirHelper(
+            os.path.isdir,
+            os.listdir,
+            os.walk,
+            shutil.rmtree
+            )
+
+    file_helper = FileSystemHelper(
+            open,
+            os.path.join,
+            shutil.move,
+            os.path.exists
+            )
+
+    operations_factory = OperationsFactory()
+    handler_factory = HandlerFactory()
+
+    layout_factory = LayoutFactory(
+            operations_factory,
+            handler_factory,
+            file_helper,
+            dir_helper,
+            opts.verbose,
+            sys.stdout,
+            force=False
+            )
+
+    layout = layout_factory.create_layout(path)
+    layout.process()
+
+
+
+if __name__ == "__main__":
+    main(sys.argv[1:])

docs/update_ghpages.sh

@@ -0,0 +1,31 b''
+#!/usr/bin/env sh
+# pick repo for gh-pages branch
+repo=origin
+
+if [ ! -d gh-pages ]; then
+    echo "setting up gh-pages subdir"
+    mkdir gh-pages || exit -1
+    cp -r ../.git gh-pages/ || exit -1
+    cd gh-pages || exit -1
+    init=0
+    git checkout $repo/gh-pages || init=1
+    if [ "$init" != "0" ]; then
+        echo "initializing gh-pages repo"
+        git symbolic-ref HEAD refs/heads/gh-pages || exit -1
+        rm .git/index || exit -1
+        git clean -fdx || exit -1
+        touch index.html
+        git add .
+        git commit -a -m 'init gh-pages' || exit -1
+        git push origin HEAD:gh-pages
+    fi
+    cd ..
+fi
+echo "updating local gh-pages with html build"
+rsync -va build/html/ gh-pages/ --delete --exclude .git || exit -1
+cd gh-pages
+git add .
+git commit -a || exit -1
+echo "pushing to remote gh-pages"
+# pwd
+git push $repo HEAD:gh-pages

.gitignore

@@ -1,10 +1,11 b''
 build
 ./dist
 docs/dist
 docs/build/*
 docs/source/api/generated
+docs/gh-pages
 *.py[co]
 build
 *.egg-info
 *~
 *.bak

docs/Makefile

@@ -1,104 +1,107 b''
 # Makefile for Sphinx documentation
 #
 
 # You can set these variables from the command line.
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
 SRCDIR        = source
 
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
 
 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
 
 default: html
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      to make standalone HTML files"
 	@echo "  pickle    to make pickle files (usable by e.g. sphinx-web)"
 	@echo "  htmlhelp  to make HTML files and a HTML help project"
 	@echo "  latex     to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
 	@echo "  changes   to make an overview over all changed/added/deprecated items"
 	@echo "  linkcheck to check all external links for integrity"
 	@echo
 	@echo "Compound utility targets:"
 	@echo "pdf          latex and then runs the PDF generation"
 	@echo "all          html and pdf"
 	@echo "dist         all, and then puts the results in dist/"
 	@echo "gitwash-update update git workflow from source repo"
 
 clean:
 	-rm -rf build/* dist/* $(SRCDIR)/api/generated
 
 pdf: latex
 	cd build/latex && make all-pdf
 
 all: html pdf
 
 dist: all
 	mkdir -p dist
 	rm -rf dist/*
 	ln build/latex/ipython.pdf dist/
 	cp -al build/html dist/
 	@echo "Build finished.  Final docs are in dist/"
 
 html: api
 	mkdir -p build/html build/doctrees
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
 	@echo
 	@echo "Build finished. The HTML pages are in build/html."
 
 api: source/api/generated/gen.txt
 
 source/api/generated/gen.txt:
 	python autogen_api.py
 	@echo "Build API docs finished."
 
 pickle:
 	mkdir -p build/pickle build/doctrees
 	$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
 	@echo
 	@echo "Build finished; now you can process the pickle files or run"
 	@echo "  sphinx-web build/pickle"
 	@echo "to start the sphinx-web server."
 
 web: pickle
 
 htmlhelp:
 	mkdir -p build/htmlhelp build/doctrees
 	$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
 	@echo
 	@echo "Build finished; now you can run HTML Help Workshop with the" \
 	      ".hhp project file in build/htmlhelp."
 
 latex: api
 	mkdir -p build/latex build/doctrees
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in build/latex."
 	@echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
 	      "run these through (pdf)latex."
 
 changes:
 	mkdir -p build/changes build/doctrees
 	$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
 	@echo
 	@echo "The overview file is in build/changes."
 
 linkcheck:
 	mkdir -p build/linkcheck build/doctrees
 	$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
 	@echo
 	@echo "Link check complete; look for any errors in the above output " \
 	      "or in build/linkcheck/output.txt."
 
 gitwash-update:
 	python ../tools/gitwash_dumper.py source/development ipython
 	cd source/development/gitwash && rename 's/.rst/.txt/' *.rst
 
 nightly: dist
 	rsync -avH --delete dist/ ipython:www/doc/nightly
+
+gh-pages: html
+	sh update_ghpages.sh

docs/source/conf.py

@@ -1,195 +1,196 b''
 # -*- coding: utf-8 -*-
 #
 # IPython documentation build configuration file.
 
 # NOTE: This file has been edited manually from the auto-generated one from
 # sphinx.  Do NOT delete and re-generate.  If any changes from sphinx are
 # needed, generate a scratch one and merge by hand any new fields needed.
 
 #
 # This file is execfile()d with the current directory set to its containing dir.
 #
 # The contents of this file are pickled, so don't put values in the namespace
 # that aren't pickleable (module imports are okay, they're removed automatically).
 #
 # All configuration values have a default value; values that are commented out
 # serve to show the default value.
 
 import sys, os
 
 # If your extensions are in another directory, add it here. If the directory
 # is relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
-sys.path.append(os.path.abspath('../sphinxext'))
+sys.path.insert(0, os.path.abspath('../sphinxext'))
 
 # Import support for ipython console session syntax highlighting (lives
 # in the sphinxext directory defined above)
 import ipython_console_highlighting
 
 # We load the ipython release info into a dict by explicit execution
 iprelease = {}
 execfile('../../IPython/core/release.py',iprelease)
 
 # General configuration
 # ---------------------
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
     # 'matplotlib.sphinxext.mathmpl',
     'matplotlib.sphinxext.only_directives',
     # 'matplotlib.sphinxext.plot_directive',
     'sphinx.ext.autodoc',
     'sphinx.ext.doctest',
     'inheritance_diagram',
     'ipython_console_highlighting', 
     'numpydoc',  # to preprocess docstrings
+    'sphinxtogithub',
 ]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
 
 # The suffix of source filenames.
 source_suffix = '.txt'
 
 # The master toctree document.
 master_doc = 'index'
 
 # General substitutions.
 project = 'IPython'
 copyright = '2008, The IPython Development Team'
 
 # The default replacements for |version| and |release|, also used in various
 # other places throughout the built documents.
 #
 # The full version, including alpha/beta/rc tags.
 release = iprelease['version']
 # The short X.Y version.
 version = '.'.join(release.split('.',2)[:2])
 
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
 #today = ''
 # Else, today_fmt is used as the format for a strftime call.
 today_fmt = '%B %d, %Y'
 
 # List of documents that shouldn't be included in the build.
 #unused_docs = []
 
 # List of directories, relative to source directories, that shouldn't be searched
 # for source files.
 exclude_dirs = ['attic']
 
 # If true, '()' will be appended to :func: etc. cross-reference text.
 #add_function_parentheses = True
 
 # If true, the current module name will be prepended to all description
 # unit titles (such as .. function::).
 #add_module_names = True
 
 # If true, sectionauthor and moduleauthor directives will be shown in the
 # output. They are ignored by default.
 #show_authors = False
 
 # The name of the Pygments (syntax highlighting) style to use.
 pygments_style = 'sphinx'
 
 
 # Options for HTML output
 # -----------------------
 
 # The style sheet to use for HTML and HTML Help pages. A file of that name
 # must exist either in Sphinx' static/ path, or in one of the custom paths
 # given in html_static_path.
 html_style = 'default.css'
 
 # The name for this set of Sphinx documents.  If None, it defaults to
 # "<project> v<release> documentation".
 #html_title = None
 
 # The name of an image file (within the static path) to place at the top of
 # the sidebar.
 #html_logo = None
 
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 html_last_updated_fmt = '%b %d, %Y'
 
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 #html_use_smartypants = True
 
 # Custom sidebar templates, maps document names to template names.
 #html_sidebars = {}
 
 # Additional templates that should be rendered to pages, maps page names to
 # template names.
 #html_additional_pages = {}
 
 # If false, no module index is generated.
 #html_use_modindex = True
 
 # If true, the reST sources are included in the HTML build as _sources/<name>.
 #html_copy_source = True
 
 # If true, an OpenSearch description file will be output, and all pages will
 # contain a <link> tag referring to it.  The value of this option must be the
 # base URL from which the finished HTML is served.
 #html_use_opensearch = ''
 
 # If nonempty, this is the file name suffix for HTML files (e.g. ".xhtml").
 #html_file_suffix = ''
 
 # Output file base name for HTML help builder.
 htmlhelp_basename = 'ipythondoc'
 
 
 # Options for LaTeX output
 # ------------------------
 
 # The paper size ('letter' or 'a4').
 latex_paper_size = 'letter'
 
 # The font size ('10pt', '11pt' or '12pt').
 latex_font_size = '11pt'
 
 # Grouping the document tree into LaTeX files. List of tuples
 # (source start file, target name, title, author, document class [howto/manual]).
 
 latex_documents = [
     ('index', 'ipython.tex', 'IPython Documentation',
      ur"""The IPython Development Team""", 'manual', True),
     ('parallel/winhpc_index', 'winhpc_whitepaper.tex',
      'Using IPython on Windows HPC Server 2008',
      ur"Brian E. Granger", 'manual', True)
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
 # the title page.
 #latex_logo = None
 
 # For "manual" documents, if this is true, then toplevel headings are parts,
 # not chapters.
 #latex_use_parts = False
 
 # Additional stuff for the LaTeX preamble.
 #latex_preamble = ''
 
 # Documents to append as an appendix to all manuals.
 #latex_appendices = []
 
 # If false, no module index is generated.
 latex_use_modindex = True
 
 
 # Cleanup
 # -------
 # delete release info to avoid pickling errors from sphinx
 
 del iprelease