Skip to content

Commit 8d42980

Browse files
matthew-brettmatthew-brett
committed
RF+DOC: refactor doc build
* Remove our own copies of numpydoc and IPython console highlighting; * update conf.py to latest Sphinx; * refactor search for nipy and version getting; * add doc and dev requirements files.
1 parent 281276b commit 8d42980

11 files changed

+79
-1042
lines changed

‎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: 54 additions & 39 deletions
Original file line numberDiff line numberDiff line change
@@ -13,36 +13,41 @@
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+
'texext.math_dollar',
44+
'sphinx.ext.doctest',
45+
'sphinx.ext.mathjax',
46+
'sphinx.ext.autosummary',
47+
'sphinx.ext.inheritance_diagram',
48+
'matplotlib.sphinxext.plot_directive',
49+
'IPython.sphinxext.ipython_console_highlighting',
50+
]
4651

4752
# Autosummary on
4853
autosummary_generate=True
@@ -56,17 +61,15 @@
5661
# The master toctree document.
5762
master_doc = 'index'
5863

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

6568
# The default replacements for |version| and |release|, also used in various
6669
# other places throughout the built documents.
6770
#
6871
# The short X.Y version.
69-
version = rel['__version__']
72+
version = project_module.__version__
7073
# The full version, including alpha/beta/rc tags.
7174
release = version
7275

@@ -164,11 +167,29 @@
164167
# Options for LaTeX output
165168
# ------------------------
166169

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

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

173194
# Grouping the document tree into LaTeX files. List of tuples
174195
# (source start file, target name, title, author, document class
@@ -183,18 +204,12 @@
183204
# the title page.
184205
#latex_logo = None
185206

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-
"""
207+
if sphinx.version_info[:2] < (1, 4):
208+
# For "manual" documents, if this is true, then toplevel headings are parts,
209+
# not chapters.
210+
latex_use_parts = True
211+
else: # Sphinx >= 1.4
212+
latex_toplevel_sectioning = 'part'
198213

199214
# Documents to append as an appendix to all manuals.
200215
#latex_appendices = []

‎doc/devel/guidelines/howto_document.rst

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,10 @@ our documents and docstrings are in reST format, this allows us to
1010
have both human-readable docstrings when viewed in ipython_, and
1111
web and print quality documentation.
1212

13+
==========================
14+
Getting build dependencies
15+
==========================
16+
1317

1418
Building the documentation
1519
--------------------------

‎doc/links_names.txt

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@
1111
__not_case_sensitive__, so only one target definition is needed for
1212
nipy, NIPY, Nipy, etc...
1313
14-
.. nipy
14+
.. Nipy
1515
.. _nipy: http://nipy.org/nipy
1616
.. _`NIPY developer resources`: http://nipy.sourceforge.net/devel
1717
.. _`NIPY data packages`: http://nipy.sourceforge.net/data-packages
@@ -25,7 +25,7 @@
2525
.. _`nipy launchpad`: https://launchpad.net/nipy
2626
.. _nipy on travis: https://travis-ci.org/nipy/nipy
2727

28-
.. other related projects
28+
.. Related projects
2929
.. _nipy community: http://nipy.org
3030
.. _dipy: http://nipy.org/dipy
3131
.. _`dipy github`: http://github.com/Garyfallidis/dipy

‎doc/sphinxext/ipython_console_highlighting.py

Lines changed: 0 additions & 100 deletions
This file was deleted.

‎doc/sphinxext/numpy_ext/__init__.py

Whitespace-only changes.

0 commit comments

Comments
 (0)