Omnibus backport for 1.4.x #3146
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
The ``InterfaceHelpWriter`` class was practically a clone of ``ApiDocWriter``. Both have been merged into one single module, having the Interface helper inherit from the ApiDocWriter.
This PR follows up on nipy#3119 (merge that one first for a clean diff, or diff against ``oesteban:maint/dedup-apigen-code``). In practice, this PR fixes several broken points of our documentation (e.g., the workflows list was empty and now it has been updated, changelog not rendered, API of pure python code not rendered by the Nipype API parser was missing, etc.). CHANGES ------- * Replaced the ``numpydoc`` sphinx extension with ``sphinxcontrib-napoleon``. * Removed autosummary sphinx extension, required by numpydoc * Cleared up ``docs/sphinxext/*``, as nothing is now used from there * Use current sphinx-apidoc/autodoc/autosummary * Removed the modref generation tooling, as it is not necessary anymore after re-enabling apidoc. * Cut building warnings down to 321 - just those we incur because our API generator. This required some fixes of some docstrings. Beyond those corresponding to the Nipype API generator, only missing links remain as warnings (for sections in the navbar). * Updated changelogs to be reStructuredText.
Building on top of nipy#3119 and nipy#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).
Co-Authored-By: Chris Markiewicz <[email protected]>
Co-Authored-By: Chris Markiewicz <[email protected]>
Co-Authored-By: Chris Markiewicz <[email protected]>
Co-Authored-By: Chris Markiewicz <[email protected]>
Co-Authored-By: Chris Markiewicz <[email protected]>
In particular, after allowing printing the inheritance of interfaces, links for ZZZCommandBase interfaces were broken, as originally filtered out and not built. Now they are being built and we are back to 5 warnings.
By removing some space concatenation of strings, some of them were r-strings and the concatenated one contained ``\n``, effectively escaping the special return-carriage. Instead of concatenating strings, the interface now accumulates the lines in a list that is joined in the end.
Master is broken -- this PR relocates the pip install of ``niflow-nipype1-workflows`` so that it happens AFTER nipype was installed.
|
Once this is merged, we should merge into Then when bugfixes are merged into |
1 task
Codecov Report
@@ Coverage Diff @@
## maint/1.4.x #3146 +/- ##
===============================================
+ Coverage 64.16% 67.57% +3.41%
===============================================
Files 293 299 +6
Lines 39222 39499 +277
Branches 5168 5220 +52
===============================================
+ Hits 25167 26693 +1526
+ Misses 13016 12091 -925
+ Partials 1039 715 -324
Continue to review full report at Codecov.
|
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Includes:
doc/conf.py#3131Acknowledgment