Merge pull request nipy#3120 from oesteban/maint/refactor-docs-build [skip ci]

DOC: Deep revision of documentation building

Author: oesteban

doc/Makefile

@@ -11,12 +11,12 @@ 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 api htmlonly latex changes linkcheck doctest
+.PHONY: help clean html nipypeapi htmlonly latex changes linkcheck doctest
 
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html      make the HTML documentation"
-	@echo "  api       	make API documents only"
+	@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,22 +33,20 @@ htmlonly:
 	@echo
 	@echo "Build finished. The HTML pages are in _build/html."
 
-api:
-	rm -rf api/generated
-	python -u ../tools/build_modref_templates.py
+nipypeapi:
 	rm -rf interfaces/generated
 	python -u ../tools/build_interface_docs.py
 	@echo "Build API docs finished."
 
-html: clean examples2rst api htmlonly
+html: clean examples2rst nipypeapi htmlonly
 	@echo "Build HTML and API finished."
 
 examples2rst:
 	mkdir -p users/examples
 	../tools/make_examples.py --no-exec
 	@echo "examples2rst finished."
 
-latex: api
+latex: nipypeapi
 	$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) _build/latex
 	@echo
 	@echo "Build finished; the LaTeX files are in _build/latex."

doc/api/index.rst

@@ -1,10 +1,15 @@
 .. _api-index:
 
-###
-API
-###
+###########################################
+Library API (application program interface)
+###########################################
+
+Information on specific functions, classes, and methods.
 
 :Release: |version|
 :Date: |today|
 
-.. include:: generated/gen.rst
+.. toctree::
+   :glob:
+
+   generated/*

doc/changelog/0.X.X-changelog renamed to doc/changelog/0.X.X-changelog.rst

@@ -1,7 +1,7 @@
 0.14.0 (November 29, 2017)
 ==========================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/13)
+(`Full changelog <https://github.com/nipy/nipype/milestone/13>`__)
 
 * FIX+MAINT: Revision of the resource monitor (https://github.com/nipy/nipype/pull/2285)
 * FIX: MultiProc mishandling crashes (https://github.com/nipy/nipype/pull/2301)
@@ -385,8 +385,10 @@ Release 0.9.0 (December 20, 2013)
         - camino.QBallMX
         - camino.LinRecon
         - camino.SFPeaks
-        One outdated interface no longer part of Camino was removed:
+
+  One outdated interface no longer part of Camino was removed:
         - camino.Conmap
+
 * ENH: Three new mrtrix interfaces were added:
         - mrtrix.GenerateDirections
         - mrtrix.FindShPeaks
@@ -713,7 +715,7 @@ Features added
 
 * General:
 
-  - Type checking of inputs and outputs using Traits from ETS_.
+  - Type checking of inputs and outputs using Traits from ETS.
   - Support for nested workflows.
   - Preliminary Slicer and AFNI support.
   - New flexible DataGrabber node.

doc/changelog/1.X.X-changelog renamed to doc/changelog/1.X.X-changelog.rst

@@ -1,7 +1,6 @@
 1.4.0 (December 20, 2019)
 =========================
-
-##### [Full changelog](https://github.com/nipy/nipype/milestone/37?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/37?closed=1>`__)
 
   * FIX: Mark strings containing regex escapes as raw (https://github.com/nipy/nipype/pull/3106)
   * ENH: Pacify DeprecationWarnings caused by nibabel 3 pre-release (https://github.com/nipy/nipype/pull/3099)
@@ -16,17 +15,14 @@
   * MNT: Fix Dorota Jarecka ORCID (https://github.com/nipy/nipype/pull/3100)
   * MNT: Drop Python 2 support (https://github.com/nipy/nipype/pull/2654)
 
-
 1.3.1 (November 12, 2019)
 =========================
-
   * FIX: Restore checking traits or bunch (https://github.com/nipy/nipype/pull/3094)
 
 
 1.3.0 (November 11, 2019)
 =========================
-
-##### [Full changelog](https://github.com/nipy/nipype/milestone/34?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/34?closed=1>`__)
 
   * FIX: Fixed typo in QwarpInputSpec Trait description (https://github.com/nipy/nipype/pull/3079)
   * FIX: Restore ``AFNICommand._get_fname``, required by some interfaces (https://github.com/nipy/nipype/pull/3071)
@@ -52,7 +48,7 @@
 
 Python 1.2.3 will be the last version to support Python 3.4.
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/35?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/35?closed=1>`__)
 
   * FIX: Patch Path.mkdir for Python 2 (https://github.com/nipy/nipype/pull/3037)
   * FIX: Drop deprecated message argument to ``FileNotFoundError`` (https://github.com/nipy/nipype/pull/3035)
@@ -71,7 +67,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.2.2 (September 07, 2019)
 ==========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/33?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/33?closed=1>`__)
 
   * FIX: Ensure ``loadpkl`` returns a not None value (https://github.com/nipy/nipype/pull/3020)
   * FIX: ``loadpkl`` failed when pklz file contained versioning info (https://github.com/nipy/nipype/pull/3017)
@@ -87,7 +83,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.2.1 (August 19, 2019)
 =======================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/32?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/32?closed=1>`__)
 
   * FIX: Resolve/rebase paths from/to results files (https://github.com/nipy/nipype/pull/2971)
   * FIX: Use ``load_resultfile`` when loading a results pickle (https://github.com/nipy/nipype/pull/2985)
@@ -97,7 +93,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
   * FIX: Docker build (https://github.com/nipy/nipype/pull/2963)
   * FIX: Remove '=' signs from EddyQuad argument specifications (https://github.com/nipy/nipype/pull/2941)
   * FIX: Set input model to bedpostx for camino.TrackBedpostxProba (https://github.com/nipy/nipype/pull/2947)
-  * FIX: Allow ``max_sh``not to be set (auto mode) (https://github.com/nipy/nipype/pull/2940)
+  * FIX: Allow ``max_sh`` to not be set (auto mode) (https://github.com/nipy/nipype/pull/2940)
   * ENH: Update mrtrix reconst.py EstimateFOD max_sh to be able to accept list (https://github.com/nipy/nipype/pull/2990)
   * ENH: Let ``indirectory`` handle ``nipype.utils.filemanip.Path`` (https://github.com/nipy/nipype/pull/2989)
   * ENH: Add resolve/rebase ``BasePath`` traits methods & tests (https://github.com/nipy/nipype/pull/2970)
@@ -114,7 +110,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.2.0 (May 09, 2019)
 ====================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/31?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/31?closed=1>`__)
 
   * FIX: Parsing of filename in AlignEpiAnatPy when filename does not have + (https://github.com/nipy/nipype/pull/2909)
   * FIX: Import nibabel reorientation bug fix (https://github.com/nipy/nipype/pull/2912)
@@ -133,7 +129,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.1.9 (February 25, 2019)
 =========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/30?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/30?closed=1>`__)
 
   * FIX: Make positional arguments to LaplacianThickness require previous argument (https://github.com/nipy/nipype/pull/2848)
   * FIX: Import math and csv modules for bids_gen_info (https://github.com/nipy/nipype/pull/2881)
@@ -149,7 +145,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.1.8 (January 28, 2019)
 ========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/29?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/29?closed=1>`__)
 
   * FIX: ANTS LaplacianThickness cmdline opts fixed up (https://github.com/nipy/nipype/pull/2846)
   * FIX: Resolve LinAlgError during SVD (https://github.com/nipy/nipype/pull/2838)
@@ -171,7 +167,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.1.7 (December 17, 2018)
 =========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/28?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/28?closed=1>`__)
 
   * FIX: Copy node list before generating a flat graph (https://github.com/nipy/nipype/pull/2828)
   * FIX: Update pytest req'd version to 3.6 (https://github.com/nipy/nipype/pull/2827)
@@ -193,7 +189,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 1.1.6 (November 26, 2018)
 =========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/27?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/27?closed=1>`__)
 
   * FIX: MapNodes fail when ``MultiProcPlugin`` passed by instance (https://github.com/nipy/nipype/pull/2786)
   * FIX: --fineTune arguments order for MeshFix command (https://github.com/nipy/nipype/pull/2780)
@@ -216,7 +212,7 @@ Python 1.2.3 will be the last version to support Python 3.4.
 
 Hotfix release.
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/26?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/26?closed=1>`__)
 
   * ENH: Allow timeouts during SLURM job status checks (https://github.com/nipy/nipype/pull/2767)
   * RF: Subclass non-daemon variants of all multiprocessing contexts (https://github.com/nipy/nipype/pull/2771)
@@ -225,7 +221,7 @@ Hotfix release.
 1.1.4 (October 31, 2018)
 ========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/25?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/25?closed=1>`__)
 
   * FIX: Python 2.7-3.7.1 compatible NonDaemonPool (https://github.com/nipy/nipype/pull/2754)
   * FIX: VRML typo (VMRL) in MeshFix (https://github.com/nipy/nipype/pull/2757)
@@ -253,7 +249,7 @@ Hotfix release.
 1.1.3 (September 24, 2018)
 ==========================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/24?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/24?closed=1>`__)
 
   * FIX: Return afni.Qwarp outputs as absolute paths (https://github.com/nipy/nipype/pull/2705)
   * FIX: Add informative error for interfaces that fail to return valid runtime object (https://github.com/nipy/nipype/pull/2692)
@@ -272,7 +268,7 @@ Hotfix release.
 
 Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/23?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/23?closed=1>`__)
 
   * FIX: Read BIDS config.json under grabbids or layout (https://github.com/nipy/nipype/pull/2679)
   * FIX: Node __repr__ and detailed graph expansion (https://github.com/nipy/nipype/pull/2669)
@@ -287,7 +283,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.1.1 (July 30, 2018)
 =====================
 
-##### [Full changelog](https://github.com/nipy/nipype/milestone/22?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/22?closed=1>`__)
 
   * FIX: Un-set incorrect default options in TOPUP (https://github.com/nipy/nipype/pull/2637)
   * FIX: Copy FSCommand.version to ReconAll.version (https://github.com/nipy/nipype/pull/2656)
@@ -309,7 +305,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.1.0 (July 04, 2018)
 =====================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/21?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/21?closed=1>`__)
 
   * RF: Futures-based MultiProc (https://github.com/nipy/nipype/pull/2598)
   * FIX: Avoid closing file descriptors on Windows (https://github.com/nipy/nipype/pull/2617)
@@ -326,7 +322,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.0.4 (May 29, 2018)
 ====================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/20?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/20?closed=1>`__)
 
   * FIX: Update logging levels in enable_debug_mode (https://github.com/nipy/nipype/pull/2595)
   * FIX: Set default result in DistributedPluginBase._clean_queue (https://github.com/nipy/nipype/pull/2596)
@@ -349,7 +345,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.0.3 (April 30, 2018)
 ======================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/19?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/19?closed=1>`__)
 
   * FIX: Propagate explicit Workflow config to Nodes (https://github.com/nipy/nipype/pull/2559)
   * FIX: Return non-enhanced volumes from dwi_flirt (https://github.com/nipy/nipype/pull/2547)
@@ -376,7 +372,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.0.2 (March 27, 2018)
 ======================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/16?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/16?closed=1>`__)
 
   * FIX: dcm2niix interface (https://github.com/nipy/nipype/pull/2498)
   * FIX: mark .niml.dset as special extension in utils.filemanip (https://github.com/nipy/nipype/pull/2495)
@@ -399,7 +395,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.0.1 (February 27, 2018)
 =========================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/16?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/16?closed=1>`__)
 
 * FIX: Small bug in freesurfer label2annot fill_thresh specs [#2377](https://github.com/nipy/nipype/pull/2377)
 * FIX: Error creating gradients in DTIRecon [#2460](https://github.com/nipy/nipype/pull/2460)
@@ -432,7 +428,7 @@ Hot-fix release, resolving incorrect dependencies in 1.1.1 wheel.
 1.0.0 (January 24, 2018)
 ========================
 
-###### [Full changelog](https://github.com/nipy/nipype/milestone/16?closed=1)
+(`Full changelog <https://github.com/nipy/nipype/milestone/16?closed=1>`__)
 
 * FIX: Change to interface workdir within ``Interface.run()`` instead Node (https://github.com/nipy/nipype/pull/2384)
 * FIX: PBS plugin submissions (https://github.com/nipy/nipype/pull/2344)

doc/changes.rst

@@ -6,6 +6,8 @@
 Changes in Nipype
 =================
 
-.. include:: ../CHANGES
+.. include:: changelog/1.X.X-changelog.rst
+
+.. include:: changelog/0.X.X-changelog.rst
 
 .. include:: links_names.txt