DOC: Documentation overhaul

Building on top of #3119 and #3129, this PR makes a deep revision of the
documentation:

  * Added a new ``build_docs`` job to CircleCI to test how it renders.
  * Minimized external machinery (under ``/tools/``) when building the
    documentation:

      1. Some minimal modifications to sphinx extensions (apidoc,
         napoleon) allow the generation of special documentation
         for nipype interfaces, as it used to be before this PR
      2. A new sphinx extension (``nipype.sphinxext.apidoc``) takes
         care of parsing and rendering inputs and outputs. They now
         look like the parameters/arguments of functions when formatted
         with numpydoc.

  * Revised the description of many interfaces and the documentation of
    the main class and the input/output specs.
  * Revised the structure of the navbar, separating out
    User-Guide/Examples, Interfaces-Index, and Devs' documentation.
  * Minimized the number of WARNINGS at documentation build to 5 (4 of
    them coming out from the auto-generated SEM tools).

Author: oesteban

.circleci/config.yml

@@ -394,6 +394,35 @@ jobs:
               ssh-add ~/.ssh/id_ed25519
               /home/circleci/nipype/tools/feedstock.sh
 
+  build_docs:
+    docker:
+      - image: python:3.7.4
+    working_directory: /tmp/src/nipype
+    environment:
+      - FSLOUTPUTTYPE: 'NIFTI'
+    steps:
+      - checkout
+          name: Check Python version and upgrade pip
+          command: |
+            python --version
+            python -m pip install -U pip
+      - run:
+          name: Install graphviz
+          command: |
+              apt-get update
+              apt-get install -y graphviz
+      - run:
+          name: Install Requirements (may contain pinned versions)
+          command: python -m pip install -r docs/requirements.txt
+      - run:
+          name: Install NiPype
+          command: python -m pip install ".[doc]"
+      - run:
+          name: Build documentation
+          command: make -C doc html
+      - store_artifacts:
+          path: /tmp/src/nipype/doc/_build/html
+
 workflows:
   version: 2
   build_test_deploy:
@@ -406,21 +435,39 @@ workflows:
               only: /.*/
       - compare_base_dockerfiles:
           filters:
+            branches:
+              ignore:
+                - /docs?\/.*/
             tags:
               only: /.*/
       - test_pytest:
           filters:
+            branches:
+              ignore:
+                - /docs?\/.*/
             tags:
               only: /.*/
           requires:
             - compare_base_dockerfiles
       - test_fmri_fsl_spm:
+          filters:
+            branches:
+              ignore:
+                - /docs?\/.*/
           requires:
             - compare_base_dockerfiles
       - test_fmri_spm_dartel_multiproc:
+          filters:
+            branches:
+              ignore:
+                - /docs?\/.*/
           requires:
             - compare_base_dockerfiles
       - test_fmri_spm_nested_fsl_feeds:
+          filters:
+            branches:
+              ignore:
+                - /docs?\/.*/
           requires:
             - compare_base_dockerfiles
       - deploy_dockerhub:

doc/Makefile

@@ -11,12 +11,11 @@ PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
 ALLSPHINXOPTS   = -d _build/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html nipypeapi htmlonly latex changes linkcheck doctest
+.PHONY: help clean html htmlonly latex changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      make the HTML documentation"
-	@echo "  nipypeapi make interface API documents only"
 	@echo "  latex     make the LaTeX, you can set PAPER=a4 or PAPER=letter"
 	@echo "  pdf		make <latex> and run the PDF generation"
 	@echo "  changes   make an overview of all changed/added/deprecated" \
@@ -33,20 +32,15 @@ htmlonly:
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 
-nipypeapi:
-	rm -rf interfaces/generated
-	python -u ../tools/build_interface_docs.py
-	@echo "Build API docs finished."
-
-html: clean examples2rst nipypeapi htmlonly
+html: clean examples2rst htmlonly
 	@echo "Build HTML and API finished."
 
-examples2rst:
+examples2rst: clean
 	mkdir -p users/examples
-	../tools/make_examples.py --no-exec
+	../tools/make_examples.py -x ../../../examples/test_spm.py --no-exec
 	@echo "examples2rst finished."
 
-latex: nipypeapi
+latex: clean
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in _build/latex."
@@ -80,18 +74,3 @@ gitwash-update:
             --project-url=http://nipy.org/nipype \
             --project-ml-url=http://mail.scipy.org/mailman/listinfo/nipy-devel
 	@echo "gitwash updated"
-
-# Sourceforge doesn't appear to have a way of copying the files
-# without specifying a username.  So we'll probably have one target
-# for each project admin
-sf_satra_nightly: html
-	@echo "Copying html files to sourceforge..."
-	scp -r _build/html/* satra,nipy@web.sourceforge.net:htdocs/nipype-nightly/
-
-sf_satra: html
-	@echo "Copying html files to sourceforge..."
-	rsync -auv _build/html/. satra,nipy@web.sourceforge.net:htdocs/nipype/.
-
-sf_filo: html
-	@echo "Copying html files to sourceforge..."
-	rsync -auv _build/html/. gorgolewski,nipy@web.sourceforge.net:htdocs/nipype/.

doc/README.txt

@@ -9,7 +9,9 @@
 
 <a class="navbar" href="{{pathto('index')}}">Home</a> ·
 <a class="navbar" href="{{pathto('quickstart')}}">Quickstart</a> ·
-<a class="navbar" href="{{pathto('documentation')}}">Documentation</a> ·
+<a class="navbar" href="{{pathto('examples')}}">User Guide and Examples</a> ·
+<a class="navbar" href="{{pathto('interfaces')}}">Interfaces Index</a> ·
+<a class="navbar" href="{{pathto('developers')}}">Developers</a> ·
 <a class="navbar" href="{{pathto('about')}}">About</a> ·
 <a class="navbar" href="http://nipy.org">Nipy</a>
 

doc/_templates/navbar.html

@@ -1,3 +1,5 @@
+:orphan:
+
 .. _about:
 
 =====

doc/about.rst

@@ -1,3 +1,4 @@
+:orphan:
 :tocdepth: 2
 
 .. _changes:

doc/api/index.rst

@@ -16,14 +16,6 @@
 from packaging.version import Version
 import nipype
 
-# if not os.path.exists('users/examples'):
-#     os.mkdir('users/examples')
-# os.system('python ../tools/make_examples.py --no-exec')
-
-# if os.path.exists('interfaces/generated'):
-#     rmtree('interfaces/generated')
-# os.system('python ../tools/build_interface_docs.py')
-
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
@@ -41,9 +33,11 @@
     'sphinx.ext.inheritance_diagram',
     'sphinx.ext.todo',
     'sphinxcontrib.apidoc',
-    'sphinxcontrib.napoleon',
     'matplotlib.sphinxext.plot_directive',
+    'nbsphinx',
     'nipype.sphinxext.plot_workflow',
+    'nipype.sphinxext.apidoc',
+    'nipype.sphinxext.documenter',
 ]
 
 autodoc_mock_imports = [
@@ -57,6 +51,8 @@
     'skimage',
     'svgutils',
     'transforms3d',
+    'tvtk',
+    'vtk'
 ]
 
 # Accept custom section names to be parsed for numpy-style docstrings
@@ -68,6 +64,8 @@
     ('Inputs', 'Parameters'),
     ('Outputs', 'Parameters'),
     ('Attributes', 'Parameters'),
+    ('Mandatory Inputs', 'Parameters'),
+    ('Optional Inputs', 'Parameters'),
 ]
 
 
@@ -122,8 +120,6 @@
 # This pattern also affects html_static_path and html_extra_path.
 exclude_patterns = [
     '_build', 'Thumbs.db', '.DS_Store',
-    'api/generated/gen.rst',
-    'interfaces/generated/gen.rst'
 ]
 
 # The reST default role (used for this markup: `text`) to use for all documents.
@@ -278,10 +274,8 @@
 apidoc_output_dir = 'api/generated'
 apidoc_excluded_paths = [
     '*/tests/*', 'tests/*',
-    'algorithms/*',
     'external/*',
     'fixes/*',
-    'interfaces/*',
     'scripts/*',
     'sphinxext/*',
     'testing/*',

doc/changes.rst

@@ -0,0 +1,17 @@
+:orphan:
+
+.. _developers:
+
+==================
+Developer's Corner
+==================
+
+.. toctree::
+    :maxdepth: 2
+
+    devel/index
+
+.. toctree::
+    :maxdepth: 3
+
+    api/generated/nipype

doc/conf.py

@@ -0,0 +1,19 @@
+:orphan:
+
+.. _examples:
+
+=======================
+User Guide and Examples
+=======================
+
+.. admonition:: Michael Notter's User Guide
+
+  Be sure to read `Michael's excellent tutorials <https://miykael.github.io/nipype_tutorial/>`__.
+
+Examples
+~~~~~~~~
+  .. toctree::
+     :maxdepth: 1
+     :glob:
+
+     users/examples/*