Merge pull request #3124 from oesteban/doc/sphinxext-interfaces

DOC: Documentation overhaul

Author: oesteban

.circleci/config.yml

@@ -99,7 +99,6 @@ _run_codecov_smoke: &_run_codecov_smoke
 
 version: 2
 jobs:
-
   compare_base_dockerfiles:
     docker:
       - image: docker:17.10.0-ce-git
@@ -394,10 +393,44 @@ 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
+      - run:
+          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 doc/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:
     jobs:
+      - build_docs:
+          filters:
+            tags:
+              only: /.*/
       - pypi_precheck:
           filters:
             branches:
@@ -406,21 +439,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:

MANIFEST.in

@@ -4,7 +4,6 @@ include MANIFEST.in
 include	README
 include THANKS
 include Makefile
-include build_docs.py
 include setup_egg.py
 include doc/documentation.zip
 include nipype/COMMIT_INFO.txt

build_docs.py

@@ -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 examples2rst
 	$(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,[email protected]:htdocs/nipype-nightly/
-
-sf_satra: html
-	@echo "Copying html files to sourceforge..."
-	rsync -auv _build/html/. satra,[email protected]:htdocs/nipype/.
-
-sf_filo: html
-	@echo "Copying html files to sourceforge..."
-	rsync -auv _build/html/. gorgolewski,[email protected]:htdocs/nipype/.

doc/Makefile

@@ -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>