Show More
@@ -1,110 +1,110 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 |
|
9 | |||
10 | # Internal variables. |
|
10 | # Internal variables. | |
11 | PAPEROPT_a4 = -D latex_paper_size=a4 |
|
11 | PAPEROPT_a4 = -D latex_paper_size=a4 | |
12 | PAPEROPT_letter = -D latex_paper_size=letter |
|
12 | PAPEROPT_letter = -D latex_paper_size=letter | |
13 | ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) |
|
13 | ALLSPHINXOPTS = -d build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) $(SRCDIR) | |
14 |
|
14 | |||
15 | .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api |
|
15 | .PHONY: help clean html web pickle htmlhelp latex changes linkcheck api | |
16 |
|
16 | |||
17 | default: html |
|
17 | default: html | |
18 |
|
18 | |||
19 | help: |
|
19 | help: | |
20 | @echo "Please use \`make <target>' where <target> is one of" |
|
20 | @echo "Please use \`make <target>' where <target> is one of" | |
21 | @echo " html to make standalone HTML files" |
|
21 | @echo " html to make standalone HTML files" | |
22 | @echo " pickle to make pickle files (usable by e.g. sphinx-web)" |
|
22 | @echo " pickle to make pickle files (usable by e.g. sphinx-web)" | |
23 | @echo " htmlhelp to make HTML files and a HTML help project" |
|
23 | @echo " htmlhelp to make HTML files and a HTML help project" | |
24 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" |
|
24 | @echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter" | |
25 | @echo " changes to make an overview over all changed/added/deprecated items" |
|
25 | @echo " changes to make an overview over all changed/added/deprecated items" | |
26 | @echo " linkcheck to check all external links for integrity" |
|
26 | @echo " linkcheck to check all external links for integrity" | |
27 | @echo |
|
27 | @echo | |
28 | @echo "Compound utility targets:" |
|
28 | @echo "Compound utility targets:" | |
29 | @echo "pdf latex and then runs the PDF generation" |
|
29 | @echo "pdf latex and then runs the PDF generation" | |
30 | @echo "all html and pdf" |
|
30 | @echo "all html and pdf" | |
31 | @echo "dist all, and then puts the results in dist/" |
|
31 | @echo "dist all, and then puts the results in dist/" | |
32 | @echo "gitwash-update update git workflow from source repo" |
|
32 | @echo "gitwash-update update git workflow from source repo" | |
33 |
|
33 | |||
34 | clean: |
|
34 | clean: | |
35 | -rm -rf build/* dist/* $(SRCDIR)/api/generated |
|
35 | -rm -rf build/* dist/* $(SRCDIR)/api/generated | |
36 |
|
36 | |||
37 | pdf: latex |
|
37 | pdf: latex | |
38 | cd build/latex && make all-pdf |
|
38 | cd build/latex && make all-pdf | |
39 |
|
39 | |||
40 | all: html pdf |
|
40 | all: html pdf | |
41 |
|
41 | |||
42 | # For final distribution, only build HTML (our pdf is now so large as to be |
|
42 | # For final distribution, only build HTML (our pdf is now so large as to be | |
43 | # unusable, takes forever to build and just bloats the downloads). We leave |
|
43 | # unusable, takes forever to build and just bloats the downloads). We leave | |
44 | # them hardlinked at the top-level so users find them easily, though the |
|
44 | # them hardlinked at the top-level so users find them easily, though the | |
45 | # original build/html dir is left in-place (useful to reload builds while |
|
45 | # original build/html dir is left in-place (useful to reload builds while | |
46 | # testing). |
|
46 | # testing). | |
47 | dist: html |
|
47 | dist: html | |
48 | rm -rf html |
|
48 | rm -rf html | |
49 | cp -al build/html . |
|
49 | cp -al build/html . | |
50 | @echo "Build finished. Final docs are in html/" |
|
50 | @echo "Build finished. Final docs are in html/" | |
51 |
|
51 | |||
52 | html: api |
|
52 | html: api | |
53 | mkdir -p build/html build/doctrees |
|
53 | mkdir -p build/html build/doctrees | |
54 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html |
|
54 | $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) build/html | |
55 | @echo |
|
55 | @echo | |
56 | @echo "Build finished. The HTML pages are in build/html." |
|
56 | @echo "Build finished. The HTML pages are in build/html." | |
57 |
|
57 | |||
58 | api: source/api/generated/gen.txt |
|
58 | api: source/api/generated/gen.txt | |
59 |
|
59 | |||
60 | source/api/generated/gen.txt: |
|
60 | source/api/generated/gen.txt: | |
61 | python autogen_api.py |
|
61 | python autogen_api.py | |
62 | @echo "Build API docs finished." |
|
62 | @echo "Build API docs finished." | |
63 |
|
63 | |||
64 | pickle: |
|
64 | pickle: | |
65 | mkdir -p build/pickle build/doctrees |
|
65 | mkdir -p build/pickle build/doctrees | |
66 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle |
|
66 | $(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) build/pickle | |
67 | @echo |
|
67 | @echo | |
68 | @echo "Build finished; now you can process the pickle files or run" |
|
68 | @echo "Build finished; now you can process the pickle files or run" | |
69 | @echo " sphinx-web build/pickle" |
|
69 | @echo " sphinx-web build/pickle" | |
70 | @echo "to start the sphinx-web server." |
|
70 | @echo "to start the sphinx-web server." | |
71 |
|
71 | |||
72 | web: pickle |
|
72 | web: pickle | |
73 |
|
73 | |||
74 | htmlhelp: |
|
74 | htmlhelp: | |
75 | mkdir -p build/htmlhelp build/doctrees |
|
75 | mkdir -p build/htmlhelp build/doctrees | |
76 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp |
|
76 | $(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) build/htmlhelp | |
77 | @echo |
|
77 | @echo | |
78 | @echo "Build finished; now you can run HTML Help Workshop with the" \ |
|
78 | @echo "Build finished; now you can run HTML Help Workshop with the" \ | |
79 | ".hhp project file in build/htmlhelp." |
|
79 | ".hhp project file in build/htmlhelp." | |
80 |
|
80 | |||
81 | latex: api |
|
81 | latex: api | |
82 | mkdir -p build/latex build/doctrees |
|
82 | mkdir -p build/latex build/doctrees | |
83 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex |
|
83 | $(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) build/latex | |
84 | @echo |
|
84 | @echo | |
85 | @echo "Build finished; the LaTeX files are in build/latex." |
|
85 | @echo "Build finished; the LaTeX files are in build/latex." | |
86 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ |
|
86 | @echo "Run \`make all-pdf' or \`make all-ps' in that directory to" \ | |
87 | "run these through (pdf)latex." |
|
87 | "run these through (pdf)latex." | |
88 |
|
88 | |||
89 | changes: |
|
89 | changes: | |
90 | mkdir -p build/changes build/doctrees |
|
90 | mkdir -p build/changes build/doctrees | |
91 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes |
|
91 | $(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) build/changes | |
92 | @echo |
|
92 | @echo | |
93 | @echo "The overview file is in build/changes." |
|
93 | @echo "The overview file is in build/changes." | |
94 |
|
94 | |||
95 | linkcheck: |
|
95 | linkcheck: | |
96 | mkdir -p build/linkcheck build/doctrees |
|
96 | mkdir -p build/linkcheck build/doctrees | |
97 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck |
|
97 | $(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) build/linkcheck | |
98 | @echo |
|
98 | @echo | |
99 | @echo "Link check complete; look for any errors in the above output " \ |
|
99 | @echo "Link check complete; look for any errors in the above output " \ | |
100 | "or in build/linkcheck/output.txt." |
|
100 | "or in build/linkcheck/output.txt." | |
101 |
|
101 | |||
102 | gitwash-update: |
|
102 | gitwash-update: | |
103 | python ../tools/gitwash_dumper.py source/development ipython |
|
103 | python ../tools/gitwash_dumper.py source/development ipython | |
104 | cd source/development/gitwash && rename 's/.rst/.txt/' *.rst |
|
104 | cd source/development/gitwash && rename 's/.rst/.txt/' *.rst | |
105 |
|
105 | |||
106 | nightly: dist |
|
106 | nightly: dist | |
107 | rsync -avH --delete dist/ ipython:www/doc/nightly |
|
107 | rsync -avH --delete dist/ ipython:www/doc/nightly | |
108 |
|
108 | |||
109 |
gh-pages: html |
|
109 | gh-pages: clean html | |
110 | python gh-pages.py |
|
110 | python gh-pages.py |
@@ -1,132 +1,136 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 | try: | |
86 | tag = sh2('git describe') |
|
86 | tag = sh2('git describe --exact-match') | |
87 | except CalledProcessError: |
|
87 | except CalledProcessError: | |
88 | tag = "dev" # Fallback |
|
88 | tag = "dev" # Fallback | |
89 |
|
89 | |||
90 | startdir = os.getcwdu() |
|
90 | startdir = os.getcwdu() | |
91 | if not os.path.exists(pages_dir): |
|
91 | if not os.path.exists(pages_dir): | |
92 | # init the repo |
|
92 | # init the repo | |
93 | init_repo(pages_dir) |
|
93 | init_repo(pages_dir) | |
94 | else: |
|
94 | else: | |
95 | # ensure up-to-date before operating |
|
95 | # ensure up-to-date before operating | |
96 | cd(pages_dir) |
|
96 | cd(pages_dir) | |
97 | sh('git checkout gh-pages') |
|
97 | sh('git checkout gh-pages') | |
98 | sh('git pull') |
|
98 | sh('git pull') | |
99 | cd(startdir) |
|
99 | cd(startdir) | |
100 |
|
100 | |||
101 | dest = pjoin(pages_dir, tag) |
|
101 | dest = pjoin(pages_dir, tag) | |
102 |
|
102 | |||
103 | # don't `make html` here, because gh-pages already depends on html in Makefile |
|
103 | # don't `make html` here, because gh-pages already depends on html in Makefile | |
104 | # sh('make html') |
|
104 | # sh('make html') | |
|
105 | if tag != 'dev': | |||
|
106 | # only build pdf for non-dev targets | |||
|
107 | sh2('make pdf') | |||
105 |
|
108 | |||
106 | # This is pretty unforgiving: we unconditionally nuke the destination |
|
109 | # This is pretty unforgiving: we unconditionally nuke the destination | |
107 | # directory, and then copy the html tree in there |
|
110 | # directory, and then copy the html tree in there | |
108 | shutil.rmtree(dest, ignore_errors=True) |
|
111 | shutil.rmtree(dest, ignore_errors=True) | |
109 | shutil.copytree(html_dir, dest) |
|
112 | shutil.copytree(html_dir, dest) | |
|
113 | if tag != 'dev': | |||
110 | shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf')) |
|
114 | shutil.copy(pjoin(pdf_dir, 'ipython.pdf'), pjoin(dest, 'ipython.pdf')) | |
111 |
|
115 | |||
112 | try: |
|
116 | try: | |
113 | cd(pages_dir) |
|
117 | cd(pages_dir) | |
114 | status = sh2('git status | head -1') |
|
118 | status = sh2('git status | head -1') | |
115 | branch = re.match('\# On branch (.*)$', status).group(1) |
|
119 | branch = re.match('\# On branch (.*)$', status).group(1) | |
116 | if branch != 'gh-pages': |
|
120 | if branch != 'gh-pages': | |
117 | e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir, |
|
121 | e = 'On %r, git branch is %r, MUST be "gh-pages"' % (pages_dir, | |
118 | branch) |
|
122 | branch) | |
119 | raise RuntimeError(e) |
|
123 | raise RuntimeError(e) | |
120 |
|
124 | |||
121 | sh('git add %s' % tag) |
|
125 | sh('git add -A %s' % tag) | |
122 | sh('git commit -m"Updated doc release: %s"' % tag) |
|
126 | sh('git commit -m"Updated doc release: %s"' % tag) | |
123 |
|
127 | |||
124 | print 'Most recent 3 commits:' |
|
128 | print 'Most recent 3 commits:' | |
125 | sys.stdout.flush() |
|
129 | sys.stdout.flush() | |
126 | sh('git --no-pager log --oneline HEAD~3..') |
|
130 | sh('git --no-pager log --oneline HEAD~3..') | |
127 | finally: |
|
131 | finally: | |
128 | cd(startdir) |
|
132 | cd(startdir) | |
129 |
|
133 | |||
130 |
|
134 | |||
131 | print 'Now verify the build in: %r' % dest |
|
135 | print 'Now verify the build in: %r' % dest | |
132 | print "If everything looks good, 'git push'" |
|
136 | print "If everything looks good, 'git push'" |
General Comments 0
You need to be logged in to leave comments.
Login now