Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

GitHub Pages (again) #267

Closed
wants to merge 3 commits into from

2 participants

@minrk
Owner

Per Fernando's concerns about growing the repo, and my failure to notice the '.nojekyll' file making sphinxtoghpages obsolete, I have adapted Fernando's datarray-doc approach to IPython, and scrubbed my previous script.

Obviously a new ipython-doc repo needs to be made, but I don't have permissions to create a new repo in the IPython organization. The first two commits of https://github.com/minrk/ipython-doc should initialize it (or three, to keep the first build of the docs themselves).

This is the output: http://minrk.github.com/ipython-doc

(I also put slightly harder edges on the logo I made a while ago, because it always felt slightly off to me)

@fperez
Owner

OK, thanks. We'll do this together in my office today then.

@minrk minrk gh-pages includes pdf
also fixed illegal image name in latex
a171e87
@minrk
Owner

Fixed the script to include html and pdf, and also can specify the description.

Also fixed the image filename that was illegal acc. latex.

I'll let you copy over the older versions from the moin page.

Current appearance:
https://ipython.github.com/ipython-doc

@fperez
Owner

Great, thanks. Question: what should we do about the rest of the material here?

http://ipython.scipy.org/moin/Documentation

There's all the stuff below the first header, and ideally we should keep all of this listed in a single location... Should we just add all of that to the index.html? I kind of hate editing html by hand for antyhing but trivial changes...

But in the long run, we really should keep a single docs page. I see two options:

  • we port all that content to the index.html page by hand, and so be it.
  • we make the index page itself be sphinx-generated and edit reST sources.

What do you think?

@fperez
Owner

BTW, it seems like we should just go ahead with this merge for now, and simply sort out improvements to the -doc repo separately, right? If so, go ahead with this one, close it, and then we'll finish up improving the index page and all that on the -doc repo.

@minrk
Owner

I'm actually fairly comfortable with HTML, so I'm not concerned about it, but if nobody else is then we can consider a reST or markdown frontpage.

As you mentioned, changes to the layout and content of the doc repo don't have anything to do with this pull, except for:

  • the pattern used for adding to the release list
  • the paths used for storing new builds

Those need to change in sync, but any other changes are independent.

@minrk
Owner

gh-pages includes pdf

also fixed illegal image name in latex

closed by 4886db0

@minrk
Owner

Merged.

I cloned the moin doc page into the index - it was pretty straightforward after a few TM macros.

@minrk
Owner

I've turned the moin content into reST, and styled the reST so it comes out just like the existing frontpage. Should I push that as well? That would change how the gh-pages script would work slightly.

@minrk
Owner

In case you are interested, the rest version can be seen here:
minrk/ipython-doc@3e189c4

and the HTML it generates is not notably different from the current appearance.

If you okay it, I'll make this change in ipython-doc and gh-pages.py. Or we can save it for later.

@fperez
Owner

I think we should go ahead, because in the long run, the maintainability of the reST in my eyes wins over the aesthetics. I'm sure later on we could put more time into styling, but that can be done once the website is redone.

But I would really like the benefit of being able to easily port the existing wiki information so the Doc page is really complete, and I don't see that being easily done if it's pure html. It's just so annoying to edit :)

So I'd say go for it in reST. Thanks!

@minrk
Owner

Okay, great. gh-pages.py and ipython-doc index page updated to use reST now, so it should be easier for more people to maintain it.

ref: 82eb507

@markvoorhies markvoorhies referenced this pull request from a commit in markvoorhies/ipython
@minrk minrk gh-pages includes pdf
also fixed illegal image name in latex

closes gh-267
4886db0
@ellisonbg ellisonbg referenced this pull request from a commit
Commit has since been removed from the repository and is no longer available.
@dwrensha dwrensha referenced this pull request from a commit
@andrewrk andrewrk require libgroove 4.1.1 or higher
closes #267
closes #138
391a1b0
@mattvonrocketstein mattvonrocketstein referenced this pull request from a commit in mattvonrocketstein/ipython
@minrk minrk gh-pages includes pdf
also fixed illegal image name in latex

closes gh-267
9c5fb07
This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Commits on Feb 10, 2011
  1. @minrk
  2. @minrk

    gave logo harder, cleaner edges

    minrk authored
  3. @minrk

    gh-pages includes pdf

    minrk authored
    also fixed illegal image name in latex
This page is out of date. Refresh to see the latest.
View
9 docs/Makefile
@@ -32,7 +32,7 @@ help:
@echo "gitwash-update update git workflow from source repo"
clean:
- -rm -rf build/* dist/* $(SRCDIR)/api/generated gh-pages
+ -rm -rf build/* dist/* $(SRCDIR)/api/generated
pdf: latex
cd build/latex && make all-pdf
@@ -103,5 +103,8 @@ gitwash-update:
nightly: dist
rsync -avH --delete dist/ ipython:www/doc/nightly
-gh-pages: html
- sh update_ghpages.sh
+gh-pages: html pdf
+ python gh-pages.py
+
+gh-pages-current: html pdf
+ python gh-pages.py current "Current Development Version"
View
158 docs/gh-pages.py
@@ -0,0 +1,158 @@
+#!/usr/bin/env python
+"""Script to commit the doc build outputs into the github-pages repo.
+
+Use:
+
+ gh-pages.py [tag]
+
+If no tag is given, the current output of 'git describe' is used. If given,
+that is how the resulting directory will be named.
+
+In practice, you should use either actual clean tags from a current build or
+something like 'current' as a stable URL for the most current version of the """
+
+#-----------------------------------------------------------------------------
+# Imports
+#-----------------------------------------------------------------------------
+import os
+import re
+import shutil
+import sys
+from os import chdir as cd
+from os.path import join as pjoin
+
+from subprocess import Popen, PIPE, CalledProcessError, check_call
+
+#-----------------------------------------------------------------------------
+# Globals
+#-----------------------------------------------------------------------------
+
+pages_dir = 'gh-pages'
+html_dir = 'build/html'
+pdf_dir = 'build/latex'
+pages_repo = 'git@github.com:ipython/ipython-doc.git'
+
+#-----------------------------------------------------------------------------
+# Functions
+#-----------------------------------------------------------------------------
+def sh(cmd):
+ """Execute command in a subshell, return status code."""
+ return check_call(cmd, shell=True)
+
+
+def sh2(cmd):
+ """Execute command in a subshell, return stdout.
+
+ Stderr is unbuffered from the subshell.x"""
+ p = Popen(cmd, stdout=PIPE, shell=True)
+ out = p.communicate()[0]
+ retcode = p.returncode
+ if retcode:
+ raise CalledProcessError(retcode, cmd)
+ else:
+ return out.rstrip()
+
+
+def sh3(cmd):
+ """Execute command in a subshell, return stdout, stderr
+
+ If anything appears in stderr, print it out to sys.stderr"""
+ p = Popen(cmd, stdout=PIPE, stderr=PIPE, shell=True)
+ out, err = p.communicate()
+ retcode = p.returncode
+ if retcode:
+ raise CalledProcessError(retcode, cmd)
+ else:
+ return out.rstrip(), err.rstrip()
+
+
+def init_repo(path):
+ """clone the gh-pages repo if we haven't already."""
+ sh("git clone %s %s"%(pages_repo, path))
+ here = os.getcwd()
+ cd(path)
+ sh('git checkout gh-pages')
+ cd(here)
+
+
+def render_htmlindex(fname, tag, desc=None):
+ if desc is None:
+ desc = tag
+
+ rel = '<li>{d}: <a href="{t}/index.html">HTML</a> and <a href="{t}/ipython.pdf">PDF</a>'.format(t=tag,d=desc)
+ rep = re.compile('<!-- RELEASE -->')
+ out = []
+ with file(fname) as f:
+ contents = f.read()
+ lines = contents.splitlines()
+ if rel in contents:
+ out = lines
+ else:
+ for line in lines:
+ out.append(line)
+ if rep.search(line):
+ out.append(rep.sub(rel, line))
+ return '\n'.join(out)+'\n'
+
+
+def new_htmlindex(fname, tag, desc=None):
+ new_page = render_htmlindex(fname, tag, desc)
+ os.rename(fname, fname+'~')
+ with file(fname, 'w') as f:
+ f.write(new_page)
+
+
+#-----------------------------------------------------------------------------
+# Script starts
+#-----------------------------------------------------------------------------
+if __name__ == '__main__':
+ # The tag can be given as a positional argument
+ try:
+ tag = sys.argv[1]
+ except IndexError:
+ tag = sh2('git describe')
+
+ try:
+ desc = sys.argv[2]
+ except IndexError:
+ desc="Release (%s)"%tag
+
+ startdir = os.getcwd()
+ if not os.path.exists(pages_dir):
+ init_repo(pages_dir)
+
+ dest = pjoin(pages_dir, tag)
+
+ # don't `make html` here, because gh-pages already depends on html in Makefile
+ # sh('make html')
+
+ # This is pretty unforgiving: we unconditionally nuke the destination
+ # directory, and then copy the html tree in there
+ shutil.rmtree(dest, ignore_errors=True)
+ shutil.copytree(html_dir, dest)
+ shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf'))
+
+ try:
+ cd(pages_dir)
+ sh('git checkout gh-pages')
+ status = sh2('git status | head -1')
+ branch = re.match('\# On branch (.*)$', status).group(1)
+ if branch != 'gh-pages':
+ e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir,
+ branch)
+ raise RuntimeError(e)
+
+ sh('git add %s' % tag)
+ new_htmlindex('index.html', tag, desc)
+ sh('git add index.html')
+ sh('git commit -m"Created new doc release, named: %s"' % tag)
+ print
+ print 'Most recent 3 commits:'
+ sys.stdout.flush()
+ sh('git --no-pager log --oneline HEAD~3..')
+ finally:
+ cd(startdir)
+
+ print
+ print 'Now verify the build in: %r' % dest
+ print "If everything looks good, 'git push'"
View
BIN  docs/source/_static/logo.png
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
1  docs/source/conf.py
@@ -44,7 +44,6 @@
'inheritance_diagram',
'ipython_console_highlighting',
'numpydoc', # to preprocess docstrings
- 'sphinxtogithub',
]
# Add any paths that contain templates here, relative to this directory.
View
0  docs/source/interactive/figs/colors.dark.png → docs/source/interactive/figs/colors_dark.png
File renamed without changes
View
2  docs/source/interactive/qtconsole.txt
@@ -120,7 +120,7 @@ styles associated with each ``--colors`` option.
Screenshot of ``ipython-qtconsole --colors dark``, which uses the 'monokai' theme by
default:
-.. image:: figs/colors.dark.png
+.. image:: figs/colors_dark.png
:width: 627px
.. Note::
View
381 docs/sphinxext/sphinxtogithub.py
@@ -1,381 +0,0 @@
-#! /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:])
View
31 docs/update_ghpages.sh
@@ -1,31 +0,0 @@
-#!/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
Something went wrong with that request. Please try again.