Skip to content

Commit c48a428

Browse files
effigieseffigies
committed
DOC: Update doc setup to match master
1 parent a221f61 commit c48a428

File tree

7 files changed

+157
-67
lines changed

7 files changed

+157
-67
lines changed

‎docs/Makefile

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ SPHINXOPTS =
66
SPHINXBUILD = sphinx-build
77
PAPER =
88
BUILDDIR = _build
9-
CURBRANCH = master
9+
OUTDIR = html
1010
PYTHONPATH = $(PWD)
1111

1212
# User-friendly check for sphinx-build
@@ -53,10 +53,13 @@ clean:
5353
rm -rf $(BUILDDIR)/*
5454
rm -rf reference/*
5555

56+
docs-coverage:
57+
PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b coverage $(ALLSPHINXOPTS) $(BUILDDIR)/coverage
58+
5659
html:
57-
PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
60+
PYTHONPATH=$(PYTHONPATH) $(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/$(OUTDIR)
5861
@echo
59-
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
62+
@echo "Build finished. The HTML pages are in $(BUILDDIR)/$(OUTDIR)."
6063

6164
dirhtml:
6265
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@@ -179,6 +182,3 @@ pseudoxml:
179182
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
180183
@echo
181184
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."
182-
183-
versioned:
184-
PYTHONPATH=$(PYTHONPATH) sphinx-versioning -vv -l ./docs/conf.py build -r $(CURBRANCH) ./docs/ docs/$(BUILDDIR)/html/

‎docs/_static/css/version-switch.css

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
.version-tree ul {
2+
list-style-type: none;
3+
}

‎docs/_static/js/version-switch.js

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
$(document).ready(function() {
2+
var pathname = window.location.pathname;
3+
var cur_ver = $("#version-slug").text().replace(/^[\n\s]+|[\n\s]+$/g, '')
4+
var major_minor = "master";
5+
if ( cur_ver.lastIndexOf(" (dev)") == -1 ) {
6+
major_minor = `${cur_ver.split('.')[0]}.${cur_ver.split('.')[1]}`
7+
}
8+
var relpath = pathname.substring(pathname.lastIndexOf(major_minor)).replace(/\/$/, '');
9+
var levels = relpath.split("/").length - 1
10+
if ( levels == 0 ) {
11+
levels = 1
12+
relpath += "/"
13+
}
14+
var versions_file = "../".repeat(levels) + "versions.json"
15+
relpath = "../".repeat(levels) + relpath
16+
relpath = relpath.replace("//", "/")
17+
console.log(`relpath="${relpath}", cur_ver="${cur_ver}"`)
18+
19+
$.getJSON(versions_file, function (data) {
20+
$("#version-slug").remove(); // Unnecessary if JSON was downloaded
21+
22+
$.each(data["tags"].reverse(), function( i, val ) {
23+
var new_path = relpath.replace(major_minor, val)
24+
var item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val}</a></li>`
25+
if ( i == 0 ) {
26+
item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val} (Latest Release)</a></li>`
27+
}
28+
$("#v-tags").append(item)
29+
});
30+
$.each(data["heads"].reverse(), function( i, val ) {
31+
var new_path = relpath.replace(major_minor, val)
32+
var item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val}</a></li>`
33+
if ( val == "master" ) {
34+
item = `<li class="toctree-l2"><a class="reference internal" href="${new_path}">${val} (Development)</a></li>`
35+
}
36+
$("#v-tags").append(item)
37+
});
38+
}).fail(function() {
39+
$("#version-menu").hide(); // JSON download failed - hide dropdown
40+
});
41+
});

‎docs/_templates/sidebar/brand.html

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
<a class="sidebar-brand{% if logo %} centered{% endif %}" href="{{ pathto(master_doc) }}">
2+
<span class="sidebar-brand-text">{{ project }}</span>
3+
<span id="version-slug" class="sidebar-brand-text">{{ version if version == release else version + ' (dev)' }}</span>
4+
</a>
5+
6+
<!-- Versions dropdown -->
7+
<div id="version-menu" class="version-tree">
8+
<ul>
9+
<li class="toctree-l1 has-children">
10+
<span class="sidebar-brand-text">{{ version if version == release else version + ' (dev)' }}</span>
11+
<input class="toctree-checkbox" id="toctree-checkbox-v" name="toctree-checkbox-v" role="switch" type="checkbox">
12+
<label for="toctree-checkbox-v"><div class="visually-hidden">Toggle child pages in navigation</div><i class="icon"><svg><use href="#svg-arrow-right"></use></svg></i></label>
13+
<ul id="v-tags"></ul>
14+
</ul>
15+
</div>

‎docs/api.rst

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,5 @@
11
Library API (application program interface)
22
===========================================
3-
43
Information on specific functions, classes, and methods.
54

65
.. toctree::

‎docs/conf.py

Lines changed: 82 additions & 50 deletions
Original file line numberDiff line numberDiff line change
@@ -18,12 +18,12 @@
1818

1919
from niworkflows import __version__, __copyright__, __packagename__
2020

21-
sys.path.append(os.path.abspath('sphinxext'))
21+
sys.path.append(os.path.abspath("sphinxext"))
2222

2323
# -- Project information -----------------------------------------------------
2424
project = __packagename__
2525
copyright = __copyright__
26-
author = 'The NiPreps Developers'
26+
author = "The NiPreps Developers"
2727

2828
# The short X.Y version
2929
version = Version(__version__).base_version
@@ -33,30 +33,30 @@
3333

3434
# -- General configuration ---------------------------------------------------
3535
extensions = [
36-
'sphinx.ext.autodoc',
37-
'sphinx.ext.doctest',
38-
'sphinx.ext.intersphinx',
39-
'sphinx.ext.coverage',
40-
'sphinx.ext.mathjax',
41-
'sphinx.ext.ifconfig',
42-
'sphinx.ext.viewcode',
43-
'sphinx.ext.githubpages',
44-
'nipype.sphinxext.plot_workflow',
45-
'sphinxcontrib.apidoc',
46-
'sphinxcontrib.napoleon'
36+
"sphinx.ext.autodoc",
37+
"sphinx.ext.coverage",
38+
"sphinx.ext.doctest",
39+
"sphinx.ext.githubpages",
40+
"sphinx.ext.ifconfig",
41+
"sphinx.ext.intersphinx",
42+
"sphinx.ext.mathjax",
43+
"sphinx.ext.viewcode",
44+
"sphinxcontrib.apidoc",
45+
"nipype.sphinxext.apidoc",
46+
"nipype.sphinxext.plot_workflow",
4747
]
4848

4949
autodoc_mock_imports = [
50-
'matplotlib',
51-
'nilearn',
52-
'nitime',
53-
'numpy',
54-
'pandas',
55-
'seaborn',
56-
'skimage',
57-
'svgutils',
58-
'templateflow',
59-
'transforms3d',
50+
"matplotlib",
51+
"nilearn",
52+
"nitime",
53+
"numpy",
54+
"pandas",
55+
"seaborn",
56+
"skimage",
57+
"svgutils",
58+
"templateflow",
59+
"transforms3d",
6060
]
6161

6262
# Accept custom section names to be parsed for numpy-style docstrings
@@ -65,21 +65,24 @@
6565
# https://github.com/sphinx-contrib/napoleon/pull/10 is merged.
6666
napoleon_use_param = False
6767
napoleon_custom_sections = [
68-
('Inputs', 'Parameters'),
69-
('Outputs', 'Parameters'),
68+
("Inputs", "Parameters"),
69+
("Outputs", "Parameters"),
70+
("Attributes", "Parameters"),
71+
("Mandatory Inputs", "Parameters"),
72+
("Optional Inputs", "Parameters"),
7073
]
7174

7275
# Add any paths that contain templates here, relative to this directory.
73-
templates_path = ['_templates']
76+
templates_path = ["_templates"]
7477

7578
# The suffix(es) of source filenames.
7679
# You can specify multiple suffix as a list of string:
7780
#
7881
# source_suffix = ['.rst', '.md']
79-
source_suffix = '.rst'
82+
source_suffix = ".rst"
8083

8184
# The master toctree document.
82-
master_doc = 'index'
85+
master_doc = "index"
8386

8487
# The language for content autogenerated by Sphinx. Refer to documentation
8588
# for a list of supported languages.
@@ -91,7 +94,13 @@
9194
# List of patterns, relative to source directory, that match files and
9295
# directories to ignore when looking for source files.
9396
# This pattern also affects html_static_path and html_extra_path.
94-
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'api/modules.rst', 'api/niworkflows.rst']
97+
exclude_patterns = [
98+
"_build",
99+
"Thumbs.db",
100+
".DS_Store",
101+
"api/modules.rst",
102+
"api/niworkflows.rst",
103+
]
95104

96105
# The name of the Pygments (syntax highlighting) style to use.
97106
pygments_style = None
@@ -102,7 +111,7 @@
102111
# The theme to use for HTML and HTML Help pages. See the documentation for
103112
# a list of builtin themes.
104113
#
105-
html_theme = 'sphinx_rtd_theme'
114+
html_theme = "furo"
106115

107116
# Theme options are theme-specific and customize the look and feel of a theme
108117
# further. For a list of options available for each theme, see the
@@ -113,7 +122,13 @@
113122
# Add any paths that contain custom static files (such as style sheets) here,
114123
# relative to this directory. They are copied after the builtin static files,
115124
# so a file named "default.css" will overwrite the builtin "default.css".
116-
html_static_path = ['_static']
125+
html_static_path = ["_static"]
126+
html_js_files = [
127+
"js/version-switch.js",
128+
]
129+
html_css_files = [
130+
"css/version-switch.css",
131+
]
117132

118133
# Custom sidebar templates, must be a dictionary that maps document names
119134
# to template names.
@@ -129,7 +144,7 @@
129144
# -- Options for HTMLHelp output ---------------------------------------------
130145

131146
# Output file base name for HTML help builder.
132-
htmlhelp_basename = 'niworkflowsdoc'
147+
htmlhelp_basename = "niworkflowsdoc"
133148

134149

135150
# -- Options for LaTeX output ------------------------------------------------
@@ -138,15 +153,12 @@
138153
# The paper size ('letterpaper' or 'a4paper').
139154
#
140155
# 'papersize': 'letterpaper',
141-
142156
# The font size ('10pt', '11pt' or '12pt').
143157
#
144158
# 'pointsize': '10pt',
145-
146159
# Additional stuff for the LaTeX preamble.
147160
#
148161
# 'preamble': '',
149-
150162
# Latex figure (float) alignment
151163
#
152164
# 'figure_align': 'htbp',
@@ -156,19 +168,21 @@
156168
# (source start file, target name, title,
157169
# author, documentclass [howto, manual, or own class]).
158170
latex_documents = [
159-
(master_doc, 'niworkflows.tex', 'NiWorkflows Documentation',
160-
'The NiPreps Developers', 'manual'),
171+
(
172+
master_doc,
173+
"niworkflows.tex",
174+
"NiWorkflows Documentation",
175+
"The NiPreps Developers",
176+
"manual",
177+
),
161178
]
162179

163180

164181
# -- Options for manual page output ------------------------------------------
165182

166183
# One entry per manual page. List of tuples
167184
# (source start file, name, description, authors, manual section).
168-
man_pages = [
169-
(master_doc, 'niworkflows', 'NiWorkflows Documentation',
170-
[author], 1)
171-
]
185+
man_pages = [(master_doc, "niworkflows", "NiWorkflows Documentation", [author], 1)]
172186

173187

174188
# -- Options for Texinfo output ----------------------------------------------
@@ -177,9 +191,15 @@
177191
# (source start file, target name, title, author,
178192
# dir menu entry, description, category)
179193
texinfo_documents = [
180-
(master_doc, 'niworkflows', 'NiWorkflows Documentation',
181-
author, 'NiWorkflows', 'One line description of project.',
182-
'Miscellaneous'),
194+
(
195+
master_doc,
196+
"niworkflows",
197+
"NiWorkflows Documentation",
198+
author,
199+
"NiWorkflows",
200+
"One line description of project.",
201+
"Miscellaneous",
202+
),
183203
]
184204

185205

@@ -198,21 +218,33 @@
198218
# epub_uid = ''
199219

200220
# A list of files that should not be packed into the epub file.
201-
epub_exclude_files = ['search.html']
221+
epub_exclude_files = ["search.html"]
202222

203223

204224
# -- Extension configuration -------------------------------------------------
205225

206-
apidoc_module_dir = '../niworkflows'
207-
apidoc_output_dir = 'api'
208-
apidoc_excluded_paths = ['conftest.py', '*/tests/*', 'tests/*', 'data/*']
226+
apidoc_module_dir = "../niworkflows"
227+
apidoc_output_dir = "api"
228+
apidoc_excluded_paths = ["conftest.py", "*/tests/*", "tests/*", "data/*"]
209229
apidoc_separate_modules = True
210-
apidoc_extra_args = ['--module-first', '-d 1', '-T']
230+
apidoc_extra_args = ["--module-first", "-d 1", "-T"]
211231

212232
# -- Options for intersphinx extension ---------------------------------------
213233

214234
# Example configuration for intersphinx: refer to the Python standard library.
215-
intersphinx_mapping = {'https://docs.python.org/': None}
235+
intersphinx_mapping = {
236+
"bids": ("https://bids-standard.github.io/pybids/", None),
237+
"matplotlib": ("https://matplotlib.org/", None),
238+
"nibabel": ("https://nipy.org/nibabel/", None),
239+
"nipype": ("https://nipype.readthedocs.io/en/latest/", None),
240+
"numpy": ("https://numpy.org/doc/stable/", None),
241+
"pandas": ("https://pandas.pydata.org/pandas-docs/dev", None),
242+
"python": ("https://docs.python.org/3/", None),
243+
"scipy": ("https://docs.scipy.org/doc/scipy-1.8.0/html-scipyorg/", None),
244+
"smriprep": ("https://www.nipreps.org/smriprep/", None),
245+
"surfplot": ("https://surfplot.readthedocs.io/en/latest/", None),
246+
"templateflow": ("https://www.templateflow.org/python-client", None),
247+
}
216248

217249
# -- Options for versioning extension ----------------------------------------
218250
scv_show_banner = True

‎docs/requirements.txt

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,13 @@
1-
git+https://github.com/AleksandarPetrov/napoleon.git@0dc3f28a309ad602be5f44a9049785a1026451b3#egg=sphinxcontrib-napoleon
2-
git+https://github.com/rwblair/sphinxcontrib-versioning.git@39b40b0b84bf872fc398feff05344051bbce0f63#egg=sphinxcontrib-versioning
3-
nbsphinx
4-
git+https://github.com/nipy/nipype.git@master#egg=nipype
5-
nitransforms >= 20.0.0rc3,<20.2
1+
furo ~= 2021.10.09
2+
matplotlib >= 2.2.0
3+
nibabel
4+
nipype >= 1.5.1
5+
numpy
66
packaging
7-
pydot>=1.2.3
7+
pydot >= 1.2.3
88
pydotplus
9-
sphinx-argparse
10-
sphinx>=2.1.2,<3.0
11-
sphinx_rtd_theme
12-
sphinxcontrib-apidoc ~= 0.3.0
9+
sphinx ~= 4.2
10+
sphinxcontrib-apidoc
11+
sphinxcontrib-napoleon
1312
templateflow
13+
nitransforms >= 20.0.0rc3

0 commit comments

Comments
 (0)