DOC: Deduplicate code for Sphinx's APIdoc generation #3119
Merged
Conversation
This file contains hidden or 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.
Codecov Report
@@ Coverage Diff @@ ## master #3119 +/- ## ========================================== - Coverage 67.83% 64.16% -3.68% ========================================== Files 295 293 -2 Lines 39302 39222 -80 Branches 5178 5168 -10 ========================================== - Hits 26661 25165 -1496 - Misses 11935 13019 +1084 - Partials 706 1038 +332
Continue to review full report at Codecov.
|
oesteban added a commit to oesteban/nipype that referenced this pull request Dec 21, 2019
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.
oesteban added a commit to oesteban/nipype that referenced this pull request Dec 21, 2019
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.
oesteban added a commit to oesteban/nipype that referenced this pull request Dec 29, 2019
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).
oesteban added a commit to oesteban/nipype that referenced this pull request Dec 29, 2019
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).
effigies pushed a commit to effigies/nipype that referenced this pull request Jan 6, 2020
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.
effigies pushed a commit to effigies/nipype that referenced this pull request Jan 6, 2020
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).
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
1 participant
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.
The
InterfaceHelpWriterclass was practically a clone ofApiDocWriter.Both have been merged into one single module, having the Interface
helper inherit from the ApiDocWriter.