Skip to content

Commit c38bd26

Browse files
matthew-brettmatthew-brett
authored
Merge pull request #429 from matthew-brett/fix-update-doc-build
MRG: refactoring doc build Remove vendored sphinx extensions, fix up code and markup for documentation build. Complete rewrite of installation instructions.
2 parents 281276b + 4fa797f commit c38bd26

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

53 files changed

+1242
-1690
lines changed

‎.travis.yml

Lines changed: 52 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -5,18 +5,22 @@
55
# - There can't be any leading "-"s - All newlines will be removed, so use
66
# ";"s
77
sudo: false # To use travis container infrastructure
8+
89
language: python
10+
911
cache:
1012
directories:
1113
- $HOME/.cache/pip
14+
1215
env:
13-
global:
14-
- DEPENDS="numpy scipy sympy matplotlib nibabel"
15-
- INSTALL_TYPE="setup"
16-
- EXTRA_WHEELS="https://5cf40426d9f06eb7461d-6fe47d9331aba7cd62fc36c7196769e4.ssl.cf2.rackcdn.com"
17-
- PRE_WHEELS="https://7933911d6844c6c53a7d-47bd50c35cd79bd838daf386af554a83.ssl.cf2.rackcdn.com"
18-
- EXTRA_PIP_FLAGS="--find-links=$EXTRA_WHEELS"
19-
- PRE_PIP_FLAGS="--pre $EXTRA_PIP_FLAGS --find-links $PRE_WHEELS"
16+
global:
17+
- DEPENDS="numpy scipy sympy matplotlib nibabel"
18+
- EXTRA_WHEELS="https://5cf40426d9f06eb7461d-6fe47d9331aba7cd62fc36c7196769e4.ssl.cf2.rackcdn.com"
19+
- PRE_WHEELS="https://7933911d6844c6c53a7d-47bd50c35cd79bd838daf386af554a83.ssl.cf2.rackcdn.com"
20+
- EXTRA_PIP_FLAGS="--find-links=$EXTRA_WHEELS"
21+
- PRE_PIP_FLAGS="--pre $EXTRA_PIP_FLAGS --find-links $PRE_WHEELS"
22+
- INSTALL_TYPE="pip"
23+
2024
python:
2125
- 3.4
2226
- 3.5
@@ -54,11 +58,28 @@ matrix:
5458
env:
5559
- INSTALL_TYPE=requirements
5660
- DEPENDS=
57-
- python: 3.6
5861
# test 3.5 against pre-release builds of everything
5962
- python: 3.5
6063
env:
6164
- EXTRA_PIP_FLAGS="$PRE_PIP_FLAGS"
65+
# test python setup.py install
66+
- python: 3.5
67+
env:
68+
- INSTALL_TYPE=setup
69+
- python: 3.5
70+
env:
71+
- INSTALL_TYPE="pip_e"
72+
- python: 3.5
73+
env:
74+
- DOC_BUILD=1
75+
addons:
76+
apt:
77+
packages:
78+
- graphviz
79+
- texlive-latex-base
80+
- texlive-latex-extra
81+
- texlive-fonts-recommended
82+
- texlive-latex-recommended
6283

6384
before_install:
6485
- source tools/travis_tools.sh
@@ -77,12 +98,17 @@ before_install:
7798
pip install coverage;
7899
pip install coveralls codecov;
79100
fi
101+
80102
# command to install dependencies
81103
# e.g. pip install -r requirements.txt # --use-mirrors
82104
install:
83105
- |
84-
if [ "$INSTALL_TYPE" == "setup" ]; then
85-
python setup.py install
106+
if [ "$INSTALL_TYPE" == "pip" ]; then
107+
pip install .
108+
elif [ "$INSTALL_TYPE" == "pip_e" ]; then
109+
pip install -e .
110+
elif [ "$INSTALL_TYPE" == "setup" ]; then
111+
python setup.py install
86112
elif [ "$INSTALL_TYPE" == "sdist" ]; then
87113
python setup_egg.py egg_info # check egg_info while we're here
88114
python setup_egg.py sdist
@@ -96,15 +122,23 @@ install:
96122
pip install -r requirements.txt
97123
python setup.py install
98124
fi
99-
# command to run tests, e.g. python setup.py test
125+
126+
# command to run tests
100127
script:
101-
# Change into an innocuous directory and find tests from installation
102-
- mkdir for_testing
103-
- cd for_testing
104-
- if [ "${COVERAGE}" == "1" ]; then
105-
cp ../.coveragerc .;
106-
COVER_ARGS="--with-coverage --cover-package nipy";
128+
- |
129+
if [ "$DOC_BUILD" ]; then # doc build
130+
pip install -r doc-requirements.txt
131+
make html-stamp pdf-stamp
132+
else
133+
# Change into an innocuous directory and find tests from installation
134+
mkdir for_testing
135+
cd for_testing
136+
if [ "${COVERAGE}" == "1" ]; then
137+
cp ../.coveragerc .
138+
COVER_ARGS="--with-coverage --cover-package nipy"
139+
fi
140+
$PYTHON ../tools/nipnost --verbosity=3 $COVER_ARGS nipy
107141
fi
108-
- $PYTHON ../tools/nipnost --verbosity=3 $COVER_ARGS nipy
142+
109143
after_success:
110144
- if [ "${COVERAGE}" == "1" ]; then coveralls; codecov; fi

‎Makefile

Lines changed: 4 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -43,9 +43,6 @@ dev: cythonize
4343
test:
4444
cd .. && $(PYTHON) -c 'import nipy; nipy.test()'
4545

46-
build:
47-
$(PYTHON) setup.py build
48-
4946
install:
5047
$(PYTHON) setup.py install
5148

@@ -113,11 +110,11 @@ recythonize:
113110
$(WWW_DIR):
114111
if [ ! -d $(WWW_DIR) ]; then mkdir -p $(WWW_DIR); fi
115112

116-
htmldoc: build
117-
cd $(DOCSRC_DIR) && PYTHONPATH=$(CURDIR):$(PYTHONPATH) $(MAKE) html
113+
htmldoc:
114+
cd $(DOCSRC_DIR) && $(MAKE) html
118115

119-
pdfdoc: build
120-
cd $(DOCSRC_DIR) && PYTHONPATH=$(CURDIR):$(PYTHONPATH) $(MAKE) latex
116+
pdfdoc:
117+
cd $(DOCSRC_DIR) && $(MAKE) latex
121118
cd $(LATEX_DIR) && $(MAKE) all-pdf
122119

123120
html: html-stamp

‎README.rst

Lines changed: 8 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -92,36 +92,25 @@ directory of the nipy distribution::
9292
is part of the nose package. Try ``nipnost --help`` to see a large number of
9393
command-line options.
9494

95-
Dependencies
95+
Installation
9696
============
9797

98-
To run NIPY, you will need:
98+
See the latest `installation instructions`_.
9999

100-
* python_ >= 2.6 (tested with 2.6, 2.7, 3.2 through 3.5)
101-
* numpy_ >= 1.6.0
102-
* scipy_ >= 0.9.0
103-
* sympy_ >= 0.7.0
104-
* nibabel_ >= 1.2
105-
106-
You will probably also like to have:
100+
License
101+
=======
107102

108-
* ipython_ for interactive work
109-
* matplotlib_ for 2D plotting
110-
* mayavi_ for 3D plotting
103+
We use the 3-clause BSD license; the full license is in the file ``LICENSE`` in
104+
the nipy distribution.
111105

106+
.. links:
112107
.. _python: http://python.org
113108
.. _numpy: http://numpy.scipy.org
114109
.. _scipy: http://www.scipy.org
115110
.. _sympy: http://sympy.org
116111
.. _nibabel: http://nipy.org/nibabel
117112
.. _ipython: http://ipython.org
118113
.. _matplotlib: http://matplotlib.org
119-
.. _mayavi: http://code.enthought.com/projects/mayavi/
120114
.. _nose: http://nose.readthedocs.org/en/latest
121115
.. _mock: https://pypi.python.org/pypi/mock
122-
123-
License
124-
=======
125-
126-
We use the 3-clause BSD license; the full license is in the file ``LICENSE``
127-
in the nipy distribution.
116+
.. _installation instructions: http://nipy.org/nipy/users/installation.html

‎dev-requirements.txt

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
# Requirements for running tests
2+
-r requirements.txt
3+
nose
4+
mock

‎doc-requirements.txt

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Requirements for building docs
2+
# Check these dependencies against doc/conf.py
3+
-r dev-requirements.txt
4+
sphinx>=1.0
5+
numpydoc
6+
matplotlib
7+
texext
8+
ipython

‎doc/README.txt

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,13 @@ you must have:
1818
* latex (for the PNG mathematics graphics)
1919
* graphviz (for the inheritance diagrams)
2020

21+
For the Python dependencies, do::
22+
23+
pip install -r ../doc-requirements.txt
24+
25+
Files and directories
26+
=====================
27+
2128
This directory contains:
2229

2330
* Makefile - the build script to build the HTML or PDF docs. Type

‎doc/conf.py

Lines changed: 62 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -13,36 +13,42 @@
1313
# serve to show the default value.
1414

1515
import sys, os
16+
from importlib import import_module
17+
18+
import sphinx
19+
20+
# Doc generation depends on being able to import project
21+
project = 'nipy'
22+
try:
23+
project_module = import_module(project)
24+
except ImportError:
25+
raise RuntimeError('Cannot import {}, please investigate'.format(project))
1626

1727
# If your extensions are in another directory, add it here. If the directory
1828
# is relative to the documentation root, use os.path.abspath to make it
1929
# absolute, like shown here.
2030
sys.path.append(os.path.abspath('sphinxext'))
2131

22-
# Get project related strings. Please do not change this line to use
23-
# execfile because execfile is not available in Python 3
24-
_info_fname = os.path.join('..', 'nipy', 'info.py')
25-
rel = {}
26-
exec(open(_info_fname, 'rt').read(), {}, rel)
27-
28-
# Import support for ipython console session syntax highlighting (lives
29-
# in the sphinxext directory defined above)
30-
import ipython_console_highlighting
31-
3232
# General configuration
3333
# ---------------------
3434

35+
# If your documentation needs a minimal Sphinx version, state it here.
36+
needs_sphinx = '1.0'
37+
3538
# Add any Sphinx extension module names here, as strings. They can be extensions
3639
# coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
37-
extensions = ['sphinx.ext.autodoc',
38-
'sphinx.ext.doctest',
39-
'sphinx.ext.mathjax',
40-
'sphinx.ext.autosummary',
41-
'sphinx.ext.inheritance_diagram',
42-
'numpy_ext.numpydoc',
43-
'matplotlib.sphinxext.plot_directive',
44-
'matplotlib.sphinxext.only_directives', # needed for above
45-
]
40+
extensions = [
41+
'texext.mathcode',
42+
'sphinx.ext.autodoc',
43+
'sphinx.ext.doctest',
44+
'sphinx.ext.mathjax',
45+
'sphinx.ext.autosummary',
46+
'texext.math_dollar',
47+
'numpydoc',
48+
'sphinx.ext.inheritance_diagram',
49+
'matplotlib.sphinxext.plot_directive',
50+
'IPython.sphinxext.ipython_console_highlighting',
51+
]
4652

4753
# Autosummary on
4854
autosummary_generate=True
@@ -56,17 +62,15 @@
5662
# The master toctree document.
5763
master_doc = 'index'
5864

59-
# General substitutions.
60-
project = 'nipy'
61-
62-
#copyright = ':ref:`2005-2010, Neuroimaging in Python team. <nipy-software-license>`'
65+
# copyright = ':ref:`2005-2017, Neuroimaging in Python team.
66+
# <nipy-software-license>`'
6367
copyright = '2005-2017, Neuroimaging in Python team'
6468

6569
# The default replacements for |version| and |release|, also used in various
6670
# other places throughout the built documents.
6771
#
6872
# The short X.Y version.
69-
version = rel['__version__']
73+
version = project_module.__version__
7074
# The full version, including alpha/beta/rc tags.
7175
release = version
7276

@@ -164,11 +168,29 @@
164168
# Options for LaTeX output
165169
# ------------------------
166170

167-
# The paper size ('letter' or 'a4').
168-
#latex_paper_size = 'letter'
171+
# Additional stuff for the LaTeX preamble.
172+
_latex_preamble = """
173+
\usepackage{amsmath}
174+
\usepackage{amssymb}
175+
% Uncomment these two if needed
176+
%\usepackage{amsfonts}
177+
%\usepackage{txfonts}
178+
"""
179+
180+
latex_elements = {
181+
# The paper size ('letterpaper' or 'a4paper').
182+
#'papersize': 'letterpaper',
169183

170184
# The font size ('10pt', '11pt' or '12pt').
171-
#latex_font_size = '10pt'
185+
#'pointsize': '10pt',
186+
187+
# Additional stuff for the LaTeX preamble.
188+
#'preamble': '',
189+
190+
# Latex figure (float) alignment
191+
#'figure_align': 'htbp',
192+
'preamble': _latex_preamble,
193+
}
172194

173195
# Grouping the document tree into LaTeX files. List of tuples
174196
# (source start file, target name, title, author, document class
@@ -183,21 +205,22 @@
183205
# the title page.
184206
#latex_logo = None
185207

186-
# For "manual" documents, if this is true, then toplevel headings are parts,
187-
# not chapters.
188-
latex_use_parts = True
189-
190-
# Additional stuff for the LaTeX preamble.
191-
latex_preamble = """
192-
\usepackage{amsmath}
193-
\usepackage{amssymb}
194-
% Uncomment these two if needed
195-
%\usepackage{amsfonts}
196-
%\usepackage{txfonts}
197-
"""
208+
if sphinx.version_info[:2] < (1, 4):
209+
# For "manual" documents, if this is true, then toplevel headings are parts,
210+
# not chapters.
211+
latex_use_parts = True
212+
else: # Sphinx >= 1.4
213+
latex_toplevel_sectioning = 'part'
198214

199215
# Documents to append as an appendix to all manuals.
200216
#latex_appendices = []
201217

202218
# If false, no module index is generated.
203219
latex_use_modindex = True
220+
221+
# Numpy extensions
222+
# ----------------
223+
# Worked out by Steven Silvester in
224+
# https://github.com/scikit-image/scikit-image/pull/1356
225+
numpydoc_show_class_members = False
226+
numpydoc_class_members_toctree = False

‎doc/devel/guidelines/gitwash/branch_dropdown.png

15.9 KB
Loading

‎doc/devel/guidelines/gitwash/branch_list.png

-13 KB
Binary file not shown.

‎doc/devel/guidelines/gitwash/branch_list_compare.png

-10.4 KB
Binary file not shown.

0 commit comments

Comments
 (0)