Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

DOC: Deduplicate code for Sphinx's APIdoc generation #3119

Merged
merged 1 commit into from
Dec 29, 2019
Merged

DOC: Deduplicate code for Sphinx's APIdoc generation #3119

merged 1 commit into from
Dec 29, 2019

Conversation

oesteban
Copy link
Contributor

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.

@oesteban
DOC: Deduplicate code for Sphinx's APIdoc generation
04b8cf8 
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.
@oesteban oesteban requested a review from satra December 20, 2019 20:24
@oesteban oesteban added this to the 1.4.1 milestone Dec 20, 2019
@codecov
Copy link

codecov bot commented Dec 20, 2019 •
edited
Loading

Codecov Report

Merging #3119 into master will decrease coverage by 3.67%.
The diff coverage is n/a.

Impacted file tree graph

@@            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
Flag Coverage Δ
#smoketests ?
#unittests 64.16% <ø> (-0.91%) ⬇️
Impacted Files Coverage Δ
nipype/interfaces/nilearn.py 38.98% <0%> (-57.63%) ⬇️
nipype/workflows/__init__.py 47.05% <0%> (-52.95%) ⬇️
nipype/utils/spm_docs.py 20% <0%> (-48%) ⬇️
nipype/interfaces/freesurfer/base.py 45.68% <0%> (-32.76%) ⬇️
nipype/utils/logger.py 58.46% <0%> (-30.77%) ⬇️
nipype/algorithms/rapidart.py 34.61% <0%> (-29.59%) ⬇️
nipype/interfaces/spm/base.py 57.66% <0%> (-29.34%) ⬇️
nipype/utils/provenance.py 55.16% <0%> (-28.71%) ⬇️
nipype/interfaces/fsl/model.py 55.18% <0%> (-25.4%) ⬇️
nipype/testing/fixtures.py 76.38% <0%> (-22.23%) ⬇️
... and 37 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 4c3279c...04b8cf8. Read the comment docs.

oesteban added a commit to oesteban/nipype that referenced this pull request Dec 21, 2019
@oesteban
DOC: Deep revision of documentation building
4e1bb03 
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 oesteban mentioned this pull request Dec 21, 2019
Merged
oesteban added a commit to oesteban/nipype that referenced this pull request Dec 21, 2019
@oesteban
DOC: Deep revision of documentation building
ef25a77 
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
@oesteban
DOC: Documentation overhaul
f94d59b 
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 oesteban mentioned this pull request Dec 29, 2019
Merged
@oesteban oesteban merged commit f5a0358 into nipy:master Dec 29, 2019
oesteban added a commit to oesteban/nipype that referenced this pull request Dec 29, 2019
@oesteban
DOC: Documentation overhaul
cb1e376 
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
@oesteban @effigies
DOC: Deep revision of documentation building
722bd64 
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
@oesteban @effigies
DOC: Documentation overhaul
a51b95a 
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 effigies mentioned this pull request Jan 6, 2020
Merged
1 task
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@satra satra Awaiting requested review from satra

Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
1.4.1
Development

Successfully merging this pull request may close these issues.
1 participant
@oesteban