Skip to content

Commit 27f3d10

Browse files
stefanvstefanv
committed
Add new markdown-based lecture structure
1 parent d7c46ed commit 27f3d10

30 files changed

+264
-358
lines changed

‎.gitignore

+4
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,11 @@
1+
\#*
2+
.#*
3+
_requirements.installed
14
build
25
*.DS_Store
36
*.html
47
*.ipynb_checkpoints
58
*.pyc
69
*~
710
*pano-advanced-output.png
11+
book/lessons

‎Makefile

+21-144
Original file line numberDiff line numberDiff line change
@@ -1,153 +1,30 @@
1-
# Makefile for Sphinx documentation
2-
#
1+
SHELL=/bin/bash
32

4-
# You can set these variables from the command line.
5-
SPHINXOPTS =
6-
SPHINXBUILD = sphinx-build
7-
PAPER =
8-
BUILDDIR = build
3+
.DEFAULT_GOAL = html
94

10-
# Internal variables.
11-
PAPEROPT_a4 = -D latex_paper_size=a4
12-
PAPEROPT_letter = -D latex_paper_size=letter
13-
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14-
# the i18n builder cannot share the environment and doctrees with the others
15-
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
5+
LESSONS_DIR = lessons
6+
GENERATED_LESSONS_DIR = book/lessons
167

17-
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
8+
_requirements.installed:
9+
pip install -q -r requirements.txt
10+
touch _requirements.installed
1811

19-
help:
20-
@echo "Please use \`make <target>' where <target> is one of"
21-
@echo " html to make standalone HTML files"
22-
@echo " dirhtml to make HTML files named index.html in directories"
23-
@echo " singlehtml to make a single large HTML file"
24-
@echo " pickle to make pickle files"
25-
@echo " json to make JSON files"
26-
@echo " htmlhelp to make HTML files and a HTML help project"
27-
@echo " qthelp to make HTML files and a qthelp project"
28-
@echo " devhelp to make HTML files and a Devhelp project"
29-
@echo " epub to make an epub"
30-
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
31-
@echo " latexpdf to make LaTeX files and run them through pdflatex"
32-
@echo " text to make text files"
33-
@echo " man to make manual pages"
34-
@echo " texinfo to make Texinfo files"
35-
@echo " info to make Texinfo files and run them through makeinfo"
36-
@echo " gettext to make PO message catalogs"
37-
@echo " changes to make an overview of all changed/added/deprecated items"
38-
@echo " linkcheck to check all external links for integrity"
39-
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
12+
MARKDOWNS = $(wildcard $(LESSONS_DIR)/*.md)
13+
MD_OUTPUTS = $(patsubst $(LESSONS_DIR)/%.md, $(GENERATED_LESSONS_DIR)/%.md, $(MARKDOWNS))
14+
NOTEBOOKS = $(patsubst %.md, %.ipynb, $(MD_OUTPUTS))
4015

41-
clean:
42-
-rm -rf $(BUILDDIR)/*
43-
44-
html:
45-
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
46-
@echo
47-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
48-
49-
dirhtml:
50-
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
51-
@echo
52-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
53-
54-
singlehtml:
55-
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
56-
@echo
57-
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
58-
59-
pickle:
60-
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
61-
@echo
62-
@echo "Build finished; now you can process the pickle files."
63-
64-
json:
65-
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
66-
@echo
67-
@echo "Build finished; now you can process the JSON files."
68-
69-
htmlhelp:
70-
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
71-
@echo
72-
@echo "Build finished; now you can run HTML Help Workshop with the" \
73-
".hhp project file in $(BUILDDIR)/htmlhelp."
74-
75-
qthelp:
76-
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
77-
@echo
78-
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
79-
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
80-
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/scikit-imagetutorials.qhcp"
81-
@echo "To view the help file:"
82-
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/scikit-imagetutorials.qhc"
83-
84-
devhelp:
85-
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
86-
@echo
87-
@echo "Build finished."
88-
@echo "To view the help file:"
89-
@echo "# mkdir -p $$HOME/.local/share/devhelp/scikit-imagetutorials"
90-
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/scikit-imagetutorials"
91-
@echo "# devhelp"
16+
.SECONDARY: MD_OUTPUTS
9217

93-
epub:
94-
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
95-
@echo
96-
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
18+
$(GENERATED_LESSONS_DIR)/%.ipynb:$(LESSONS_DIR)/%.md
19+
notedown $< > $@
20+
jupyter nbconvert --execute --inplace $@ --ExecutePreprocessor.timeout=-1
9721

98-
latex:
99-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
100-
@echo
101-
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
102-
@echo "Run \`make' in that directory to run these through (pdf)latex" \
103-
"(use \`make latexpdf' here to do that automatically)."
22+
%.md:%.ipynb
23+
jupyter nbconvert --to=mdoutput --output=`basename $@` --output-dir=$(GENERATED_LESSONS_DIR) $<
10424

105-
latexpdf:
106-
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
107-
@echo "Running LaTeX files through pdflatex..."
108-
$(MAKE) -C $(BUILDDIR)/latex all-pdf
109-
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
25+
html: | _requirements.installed $(NOTEBOOKS) $(MD_OUTPUTS)
26+
@export SPHINXOPTS=-W; make -C book html
27+
cp $(GENERATED_LESSONS_DIR)/*.ipynb book/build/html/lessons/
11028

111-
text:
112-
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
113-
@echo
114-
@echo "Build finished. The text files are in $(BUILDDIR)/text."
115-
116-
man:
117-
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
118-
@echo
119-
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
120-
121-
texinfo:
122-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
123-
@echo
124-
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
125-
@echo "Run \`make' in that directory to run these through makeinfo" \
126-
"(use \`make info' here to do that automatically)."
127-
128-
info:
129-
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
130-
@echo "Running Texinfo files through makeinfo..."
131-
make -C $(BUILDDIR)/texinfo info
132-
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
133-
134-
gettext:
135-
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
136-
@echo
137-
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
138-
139-
changes:
140-
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
141-
@echo
142-
@echo "The overview file is in $(BUILDDIR)/changes."
143-
144-
linkcheck:
145-
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
146-
@echo
147-
@echo "Link check complete; look for any errors in the above output " \
148-
"or in $(BUILDDIR)/linkcheck/output.txt."
149-
150-
doctest:
151-
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
152-
@echo "Testing of doctests in the sources finished, look at the " \
153-
"results in $(BUILDDIR)/doctest/output.txt."
29+
clean:
30+
rm -f $(GENERATED_LESSONS_DIR)/*

‎book/Makefile

+153
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
# Makefile for Sphinx documentation
2+
#
3+
4+
# You can set these variables from the command line.
5+
SPHINXOPTS =
6+
SPHINXBUILD = sphinx-build
7+
PAPER =
8+
BUILDDIR = build
9+
10+
# Internal variables.
11+
PAPEROPT_a4 = -D latex_paper_size=a4
12+
PAPEROPT_letter = -D latex_paper_size=letter
13+
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
14+
# the i18n builder cannot share the environment and doctrees with the others
15+
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
16+
17+
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
18+
19+
help:
20+
@echo "Please use \`make <target>' where <target> is one of"
21+
@echo " html to make standalone HTML files"
22+
@echo " dirhtml to make HTML files named index.html in directories"
23+
@echo " singlehtml to make a single large HTML file"
24+
@echo " pickle to make pickle files"
25+
@echo " json to make JSON files"
26+
@echo " htmlhelp to make HTML files and a HTML help project"
27+
@echo " qthelp to make HTML files and a qthelp project"
28+
@echo " devhelp to make HTML files and a Devhelp project"
29+
@echo " epub to make an epub"
30+
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
31+
@echo " latexpdf to make LaTeX files and run them through pdflatex"
32+
@echo " text to make text files"
33+
@echo " man to make manual pages"
34+
@echo " texinfo to make Texinfo files"
35+
@echo " info to make Texinfo files and run them through makeinfo"
36+
@echo " gettext to make PO message catalogs"
37+
@echo " changes to make an overview of all changed/added/deprecated items"
38+
@echo " linkcheck to check all external links for integrity"
39+
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
40+
41+
clean:
42+
-rm -rf $(BUILDDIR)/*
43+
44+
html:
45+
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
46+
@echo
47+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
48+
49+
dirhtml:
50+
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
51+
@echo
52+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
53+
54+
singlehtml:
55+
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
56+
@echo
57+
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
58+
59+
pickle:
60+
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
61+
@echo
62+
@echo "Build finished; now you can process the pickle files."
63+
64+
json:
65+
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
66+
@echo
67+
@echo "Build finished; now you can process the JSON files."
68+
69+
htmlhelp:
70+
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
71+
@echo
72+
@echo "Build finished; now you can run HTML Help Workshop with the" \
73+
".hhp project file in $(BUILDDIR)/htmlhelp."
74+
75+
qthelp:
76+
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
77+
@echo
78+
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
79+
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
80+
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/scikit-imagetutorials.qhcp"
81+
@echo "To view the help file:"
82+
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/scikit-imagetutorials.qhc"
83+
84+
devhelp:
85+
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
86+
@echo
87+
@echo "Build finished."
88+
@echo "To view the help file:"
89+
@echo "# mkdir -p $$HOME/.local/share/devhelp/scikit-imagetutorials"
90+
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/scikit-imagetutorials"
91+
@echo "# devhelp"
92+
93+
epub:
94+
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
95+
@echo
96+
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
97+
98+
latex:
99+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
100+
@echo
101+
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
102+
@echo "Run \`make' in that directory to run these through (pdf)latex" \
103+
"(use \`make latexpdf' here to do that automatically)."
104+
105+
latexpdf:
106+
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
107+
@echo "Running LaTeX files through pdflatex..."
108+
$(MAKE) -C $(BUILDDIR)/latex all-pdf
109+
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
110+
111+
text:
112+
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
113+
@echo
114+
@echo "Build finished. The text files are in $(BUILDDIR)/text."
115+
116+
man:
117+
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
118+
@echo
119+
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
120+
121+
texinfo:
122+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
123+
@echo
124+
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
125+
@echo "Run \`make' in that directory to run these through makeinfo" \
126+
"(use \`make info' here to do that automatically)."
127+
128+
info:
129+
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
130+
@echo "Running Texinfo files through makeinfo..."
131+
make -C $(BUILDDIR)/texinfo info
132+
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
133+
134+
gettext:
135+
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
136+
@echo
137+
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
138+
139+
changes:
140+
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
141+
@echo
142+
@echo "The overview file is in $(BUILDDIR)/changes."
143+
144+
linkcheck:
145+
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
146+
@echo
147+
@echo "Link check complete; look for any errors in the above output " \
148+
"or in $(BUILDDIR)/linkcheck/output.txt."
149+
150+
doctest:
151+
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
152+
@echo "Testing of doctests in the sources finished, look at the " \
153+
"results in $(BUILDDIR)/doctest/output.txt."

‎_static/docversions.js renamed to ‎book/_static/docversions.js

File renamed without changes.

‎_static/random.js renamed to ‎book/_static/random.js

File renamed without changes.

‎book/_static/sphinx_rtd_customize.css

+11
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
div.highlight-output {
2+
background-color: #EAEAF2;
3+
}
4+
5+
code.docutils.literal {
6+
font-family: monospace;
7+
border: 0px;
8+
color: #2980B9;
9+
padding: 0;
10+
font-size: 0.85em;
11+
}

‎_templates/localtoc.html renamed to ‎book/_templates/localtoc.html

File renamed without changes.

‎_templates/navbar.html renamed to ‎book/_templates/navbar.html

File renamed without changes.

‎_templates/navigation.html renamed to ‎book/_templates/navigation.html

File renamed without changes.

‎_templates/versions.html renamed to ‎book/_templates/versions.html

File renamed without changes.

‎conf.py renamed to ‎book/conf.py

+16-5
Original file line numberDiff line numberDiff line change
@@ -40,8 +40,8 @@
4040
master_doc = 'index'
4141

4242
# General information about the project.
43-
project = u'scikit-image tutorials'
44-
copyright = u'2014, scikit-image devs'
43+
project = u'Learn scikit-image'
44+
copyright = u'2016, scikit-image devs'
4545

4646
# The version info for the project you're documenting, acts as replacement for
4747
# |version| and |release|, also used in various other places throughout the
@@ -90,16 +90,17 @@
9090
# -- Options for HTML output ---------------------------------------------------
9191

9292
# The theme to use for HTML and HTML Help pages. See the documentation for
93-
# a list of builtin themes.
94-
html_theme = 'scikit-image'
93+
# a list of builtin themes.<F4>
94+
import sphinx_rtd_theme
95+
html_theme = 'sphinx_rtd_theme'
9596

9697
# Theme options are theme-specific and customize the look and feel of a theme
9798
# further. For a list of options available for each theme, see the
9899
# documentation.
99100
#html_theme_options = {}
100101

101102
# Add any paths that contain custom themes here, relative to this directory.
102-
html_theme_path = ['themes']
103+
html_theme_path = ['themes', sphinx_rtd_theme.get_html_theme_path()]
103104

104105
# The name for this set of Sphinx documents. If None, it defaults to
105106
# "<project> v<release> documentation".
@@ -240,3 +241,13 @@
240241

241242
# How to display URL addresses: 'footnote', 'no', or 'inline'.
242243
#texinfo_show_urls = 'footnote'
244+
245+
from recommonmark.parser import CommonMarkParser
246+
247+
source_parsers = {
248+
'.md': CommonMarkParser,
249+
}
250+
source_suffix = ['.rst', '.md', '.txt']
251+
252+
def setup(app):
253+
app.add_stylesheet("sphinx_rtd_customize.css")

0 commit comments

Comments
 (0)