##// END OF EJS Templates
require specifying the version for gh-pages...
MinRK -
Show More
@@ -1,151 +1,154 b''
1 # Makefile for Sphinx documentation
1 # Makefile for Sphinx documentation
2 #
2 #
3
3
4 # You can set these variables from the command line.
4 # You can set these variables from the command line.
5 SPHINXOPTS =
5 SPHINXOPTS =
6 SPHINXBUILD = sphinx-build
6 SPHINXBUILD = sphinx-build
7 PAPER =
7 PAPER =
8 SRCDIR = source
8 SRCDIR = source
9 BUILDDIR = build
9 BUILDDIR = build
10
10
11 # Internal variables.
11 # Internal variables.
12 PAPEROPT_a4 = -D latex_paper_size=a4
12 PAPEROPT_a4 = -D latex_paper_size=a4
13 PAPEROPT_letter = -D latex_paper_size=letter
13 PAPEROPT_letter = -D latex_paper_size=letter
14 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
14 ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR)
15
15
16 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
16 .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api
17
17
18 default: html
18 default: html
19
19
20 help:
20 help:
21 @echo "Please use \`make <target>' where <target> is one of"
21 @echo "Please use \`make <target>' where <target> is one of"
22 @echo " html standalone HTML files"
22 @echo " html standalone HTML files"
23 @echo " html_noapi same as above, without the time consuming API docs"
23 @echo " html_noapi same as above, without the time consuming API docs"
24 @echo " pickle pickle files (usable by e.g. sphinx-web)"
24 @echo " pickle pickle files (usable by e.g. sphinx-web)"
25 @echo " htmlhelp HTML files and a HTML help project"
25 @echo " htmlhelp HTML files and a HTML help project"
26 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
26 @echo " latex LaTeX files, you can set PAPER=a4 or PAPER=letter"
27 @echo " texinfo Texinfo files"
27 @echo " texinfo Texinfo files"
28 @echo " info Texinfo files and run them through makeinfo"
28 @echo " info Texinfo files and run them through makeinfo"
29 @echo " changes an overview over all changed/added/deprecated items"
29 @echo " changes an overview over all changed/added/deprecated items"
30 @echo " linkcheck check all external links for integrity (takes a long time)"
30 @echo " linkcheck check all external links for integrity (takes a long time)"
31 @echo
31 @echo
32 @echo "Compound utility targets:"
32 @echo "Compound utility targets:"
33 @echo "pdf latex and then runs the PDF generation"
33 @echo "pdf latex and then runs the PDF generation"
34 @echo "all html and pdf"
34 @echo "all html and pdf"
35 @echo "dist all, and then puts the results in dist/"
35 @echo "dist all, and then puts the results in dist/"
36 @echo "gitwash-update update git workflow from source repo"
36 @echo "gitwash-update update git workflow from source repo"
37
37
38 clean_api:
38 clean_api:
39 -rm -rf $(SRCDIR)/api/generated
39 -rm -rf $(SRCDIR)/api/generated
40
40
41 clean: clean_api
41 clean: clean_api
42 -rm -rf build/* dist/*
42 -rm -rf build/* dist/*
43 -rm -rf $(SRCDIR)/config/options/generated
43 -rm -rf $(SRCDIR)/config/options/generated
44
44
45 pdf: latex
45 pdf: latex
46 cd build/latex && make all-pdf
46 cd build/latex && make all-pdf
47
47
48 all: html pdf
48 all: html pdf
49
49
50 # For final distribution, only build HTML (our pdf is now so large as to be
50 # For final distribution, only build HTML (our pdf is now so large as to be
51 # unusable, takes forever to build and just bloats the downloads). We leave
51 # unusable, takes forever to build and just bloats the downloads). We leave
52 # them hardlinked at the top-level so users find them easily, though the
52 # them hardlinked at the top-level so users find them easily, though the
53 # original build/html dir is left in-place (useful to reload builds while
53 # original build/html dir is left in-place (useful to reload builds while
54 # testing).
54 # testing).
55 dist: html
55 dist: html
56 rm -rf html
56 rm -rf html
57 cp -al build/html .
57 cp -al build/html .
58 @echo "Build finished. Final docs are in html/"
58 @echo "Build finished. Final docs are in html/"
59
59
60 html: api autoconfig
60 html: api autoconfig
61 html_noapi: clean_api autoconfig
61 html_noapi: clean_api autoconfig
62
62
63 html html_noapi:
63 html html_noapi:
64 mkdir -p build/html build/doctrees
64 mkdir -p build/html build/doctrees
65 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
65 $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html
66 @echo
66 @echo
67 @echo "Build finished. The HTML pages are in build/html."
67 @echo "Build finished. The HTML pages are in build/html."
68
68
69 autoconfig: source/config/options/generated
69 autoconfig: source/config/options/generated
70
70
71 source/config/options/generated:
71 source/config/options/generated:
72 python autogen_config.py
72 python autogen_config.py
73 @echo "Created docs for config options"
73 @echo "Created docs for config options"
74
74
75 api: source/api/generated/gen.txt
75 api: source/api/generated/gen.txt
76
76
77 source/api/generated/gen.txt:
77 source/api/generated/gen.txt:
78 python autogen_api.py
78 python autogen_api.py
79 @echo "Build API docs finished."
79 @echo "Build API docs finished."
80
80
81 pickle:
81 pickle:
82 mkdir -p build/pickle build/doctrees
82 mkdir -p build/pickle build/doctrees
83 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
83 $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle
84 @echo
84 @echo
85 @echo "Build finished; now you can process the pickle files or run"
85 @echo "Build finished; now you can process the pickle files or run"
86 @echo " sphinx-web build/pickle"
86 @echo " sphinx-web build/pickle"
87 @echo "to start the sphinx-web server."
87 @echo "to start the sphinx-web server."
88
88
89 web: pickle
89 web: pickle
90
90
91 htmlhelp:
91 htmlhelp:
92 mkdir -p build/htmlhelp build/doctrees
92 mkdir -p build/htmlhelp build/doctrees
93 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
93 $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp
94 @echo
94 @echo
95 @echo "Build finished; now you can run HTML Help Workshop with the" \
95 @echo "Build finished; now you can run HTML Help Workshop with the" \
96 ".hhp project file in build/htmlhelp."
96 ".hhp project file in build/htmlhelp."
97
97
98 qthelp:
98 qthelp:
99 mkdir -p build/qthelp
99 mkdir -p build/qthelp
100 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
100 $(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) build/qthelp
101 @echo
101 @echo
102 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
102 @echo "Build finished; now you can run "qcollectiongenerator" with the" \
103 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
103 ".qhcp project file in $(BUILDDIR)/qthelp, like this:"
104 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
104 @echo "# qcollectiongenerator $(BUILDDIR)/qthelp/IPython.qhcp"
105 @echo "To view the help file:"
105 @echo "To view the help file:"
106 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
106 @echo "# assistant -collectionFile $(BUILDDIR)/qthelp/IPython.qhc"
107
107
108 latex: api autoconfig
108 latex: api autoconfig
109 mkdir -p build/latex build/doctrees
109 mkdir -p build/latex build/doctrees
110 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
110 $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex
111 @echo
111 @echo
112 @echo "Build finished; the LaTeX files are in build/latex."
112 @echo "Build finished; the LaTeX files are in build/latex."
113 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
113 @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \
114 "run these through (pdf)latex."
114 "run these through (pdf)latex."
115
115
116 changes:
116 changes:
117 mkdir -p build/changes build/doctrees
117 mkdir -p build/changes build/doctrees
118 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
118 $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes
119 @echo
119 @echo
120 @echo "The overview file is in build/changes."
120 @echo "The overview file is in build/changes."
121
121
122 linkcheck:
122 linkcheck:
123 mkdir -p build/linkcheck build/doctrees
123 mkdir -p build/linkcheck build/doctrees
124 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
124 $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck
125 @echo
125 @echo
126 @echo "Link check complete; look for any errors in the above output " \
126 @echo "Link check complete; look for any errors in the above output " \
127 "or in build/linkcheck/output.rst."
127 "or in build/linkcheck/output.rst."
128
128
129 gitwash-update:
129 gitwash-update:
130 python ../tools/gitwash_dumper.py source/development ipython
130 python ../tools/gitwash_dumper.py source/development ipython
131
131
132 nightly: dist
132 nightly: dist
133 rsync -avH --delete dist/ ipython:www/doc/nightly
133 rsync -avH --delete dist/ ipython:www/doc/nightly
134
134
135 gh-pages: clean html
135 gh-pages: clean html
136 python gh-pages.py
136 # if VERSION is unspecified, it will be dev
137 # For releases, VERSION should be just the major version,
138 # e.g. VERSION=2 make gh-pages
139 python gh-pages.py $(VERSION)
137
140
138 texinfo:
141 texinfo:
139 mkdir -p $(BUILDDIR)/texinfo
142 mkdir -p $(BUILDDIR)/texinfo
140 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
143 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
141 @echo
144 @echo
142 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
145 @echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
143 @echo "Run \`make' in that directory to run these through makeinfo" \
146 @echo "Run \`make' in that directory to run these through makeinfo" \
144 "(use \`make info' here to do that automatically)."
147 "(use \`make info' here to do that automatically)."
145
148
146 info:
149 info:
147 mkdir -p $(BUILDDIR)/texinfo
150 mkdir -p $(BUILDDIR)/texinfo
148 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
151 $(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
149 @echo "Running Texinfo files through makeinfo..."
152 @echo "Running Texinfo files through makeinfo..."
150 make -C $(BUILDDIR)/texinfo info
153 make -C $(BUILDDIR)/texinfo info
151 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
154 @echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
@@ -1,138 +1,134 b''
1 #!/usr/bin/env python
1 #!/usr/bin/env python
2 """Script to commit the doc build outputs into the github-pages repo.
2 """Script to commit the doc build outputs into the github-pages repo.
3
3
4 Use:
4 Use:
5
5
6 gh-pages.py [tag]
6 gh-pages.py [tag]
7
7
8 If no tag is given, the current output of 'git describe' is used. If given,
8 If no tag is given, the current output of 'git describe' is used. If given,
9 that is how the resulting directory will be named.
9 that is how the resulting directory will be named.
10
10
11 In practice, you should use either actual clean tags from a current build or
11 In practice, you should use either actual clean tags from a current build or
12 something like 'current' as a stable URL for the most current version of the """
12 something like 'current' as a stable URL for the most current version of the """
13
13
14 #-----------------------------------------------------------------------------
14 #-----------------------------------------------------------------------------
15 # Imports
15 # Imports
16 #-----------------------------------------------------------------------------
16 #-----------------------------------------------------------------------------
17 import os
17 import os
18 import re
18 import re
19 import shutil
19 import shutil
20 import sys
20 import sys
21 from os import chdir as cd
21 from os import chdir as cd
22 from os.path import join as pjoin
22 from os.path import join as pjoin
23
23
24 from subprocess import Popen, PIPE, CalledProcessError, check_call
24 from subprocess import Popen, PIPE, CalledProcessError, check_call
25
25
26 #-----------------------------------------------------------------------------
26 #-----------------------------------------------------------------------------
27 # Globals
27 # Globals
28 #-----------------------------------------------------------------------------
28 #-----------------------------------------------------------------------------
29
29
30 pages_dir = 'gh-pages'
30 pages_dir = 'gh-pages'
31 html_dir = 'build/html'
31 html_dir = 'build/html'
32 pdf_dir = 'build/latex'
32 pdf_dir = 'build/latex'
33 pages_repo = 'git@github.com:ipython/ipython-doc.git'
33 pages_repo = 'git@github.com:ipython/ipython-doc.git'
34
34
35 #-----------------------------------------------------------------------------
35 #-----------------------------------------------------------------------------
36 # Functions
36 # Functions
37 #-----------------------------------------------------------------------------
37 #-----------------------------------------------------------------------------
38 def sh(cmd):
38 def sh(cmd):
39 """Execute command in a subshell, return status code."""
39 """Execute command in a subshell, return status code."""
40 return check_call(cmd, shell=True)
40 return check_call(cmd, shell=True)
41
41
42
42
43 def sh2(cmd):
43 def sh2(cmd):
44 """Execute command in a subshell, return stdout.
44 """Execute command in a subshell, return stdout.
45
45
46 Stderr is unbuffered from the subshell.x"""
46 Stderr is unbuffered from the subshell.x"""
47 p = Popen(cmd, stdout=PIPE, shell=True)
47 p = Popen(cmd, stdout=PIPE, shell=True)
48 out = p.communicate()[0]
48 out = p.communicate()[0]
49 retcode = p.returncode
49 retcode = p.returncode
50 if retcode:
50 if retcode:
51 raise CalledProcessError(retcode, cmd)
51 raise CalledProcessError(retcode, cmd)
52 else:
52 else:
53 return out.rstrip()
53 return out.rstrip()
54
54
55
55
56 def sh3(cmd):
56 def sh3(cmd):
57 """Execute command in a subshell, return stdout, stderr
57 """Execute command in a subshell, return stdout, stderr
58
58
59 If anything appears in stderr, print it out to sys.stderr"""
59 If anything appears in stderr, print it out to sys.stderr"""
60 p = Popen(cmd, stdout=PIPE, stderr=PIPE, shell=True)
60 p = Popen(cmd, stdout=PIPE, stderr=PIPE, shell=True)
61 out, err = p.communicate()
61 out, err = p.communicate()
62 retcode = p.returncode
62 retcode = p.returncode
63 if retcode:
63 if retcode:
64 raise CalledProcessError(retcode, cmd)
64 raise CalledProcessError(retcode, cmd)
65 else:
65 else:
66 return out.rstrip(), err.rstrip()
66 return out.rstrip(), err.rstrip()
67
67
68
68
69 def init_repo(path):
69 def init_repo(path):
70 """clone the gh-pages repo if we haven't already."""
70 """clone the gh-pages repo if we haven't already."""
71 sh("git clone %s %s"%(pages_repo, path))
71 sh("git clone %s %s"%(pages_repo, path))
72 here = os.getcwdu()
72 here = os.getcwdu()
73 cd(path)
73 cd(path)
74 sh('git checkout gh-pages')
74 sh('git checkout gh-pages')
75 cd(here)
75 cd(here)
76
76
77 #-----------------------------------------------------------------------------
77 #-----------------------------------------------------------------------------
78 # Script starts
78 # Script starts
79 #-----------------------------------------------------------------------------
79 #-----------------------------------------------------------------------------
80 if __name__ == '__main__':
80 if __name__ == '__main__':
81 # The tag can be given as a positional argument
81 # The tag can be given as a positional argument
82 try:
82 try:
83 tag = sys.argv[1]
83 tag = sys.argv[1]
84 except IndexError:
84 except IndexError:
85 try:
85 tag = "dev"
86 tag = sh2('git describe --exact-match')
87 except CalledProcessError:
88 tag = "dev" # Fallback
89
86
90 startdir = os.getcwdu()
87 startdir = os.getcwdu()
91 if not os.path.exists(pages_dir):
88 if not os.path.exists(pages_dir):
92 # init the repo
89 # init the repo
93 init_repo(pages_dir)
90 init_repo(pages_dir)
94 else:
91 else:
95 # ensure up-to-date before operating
92 # ensure up-to-date before operating
96 cd(pages_dir)
93 cd(pages_dir)
97 sh('git checkout gh-pages')
94 sh('git checkout gh-pages')
98 sh('git pull')
95 sh('git pull')
99 cd(startdir)
96 cd(startdir)
100
97
101 dest = pjoin(pages_dir, tag)
98 dest = pjoin(pages_dir, tag)
102
99
103 # don't `make html` here, because gh-pages already depends on html in Makefile
100 # don't `make html` here, because gh-pages already depends on html in Makefile
104 # sh('make html')
101 # sh('make html')
105 if tag != 'dev':
102 if tag != 'dev':
106 # only build pdf for non-dev targets
103 # only build pdf for non-dev targets
107 #sh2('make pdf')
104 #sh2('make pdf')
108 pass
105 pass
109
106
110 # This is pretty unforgiving: we unconditionally nuke the destination
107 # This is pretty unforgiving: we unconditionally nuke the destination
111 # directory, and then copy the html tree in there
108 # directory, and then copy the html tree in there
112 shutil.rmtree(dest, ignore_errors=True)
109 shutil.rmtree(dest, ignore_errors=True)
113 shutil.copytree(html_dir, dest)
110 shutil.copytree(html_dir, dest)
114 if tag != 'dev':
111 if tag != 'dev':
115 #shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf'))
112 #shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf'))
116 pass
113 pass
117
114
118 try:
115 try:
119 cd(pages_dir)
116 cd(pages_dir)
120 status = sh2('git status | head -1')
117 branch = sh2('git rev-parse --abbrev-ref HEAD').strip()
121 branch = re.match('\# On branch (.*)$', status).group(1)
122 if branch != 'gh-pages':
118 if branch != 'gh-pages':
123 e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir,
119 e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir,
124 branch)
120 branch)
125 raise RuntimeError(e)
121 raise RuntimeError(e)
126
122
127 sh('git add -A %s' % tag)
123 sh('git add -A %s' % tag)
128 sh('git commit -m"Updated doc release: %s"' % tag)
124 sh('git commit -m"Updated doc release: %s"' % tag)
129 print
125 print
130 print 'Most recent 3 commits:'
126 print 'Most recent 3 commits:'
131 sys.stdout.flush()
127 sys.stdout.flush()
132 sh('git --no-pager log --oneline HEAD~3..')
128 sh('git --no-pager log --oneline HEAD~3..')
133 finally:
129 finally:
134 cd(startdir)
130 cd(startdir)
135
131
136 print
132 print
137 print 'Now verify the build in: %r' % dest
133 print 'Now verify the build in: %r' % dest
138 print "If everything looks good, 'git push'"
134 print "If everything looks good, 'git push'"
General Comments 0
You need to be logged in to leave comments. Login now