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.

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

This fixes a bunch of Sphinx warnings #3461

Merged
merged 14 commits into from Sep 13, 2014

Conversation

jenshnielsen
Copy link
Member

Not all warnings yet but should correct a number of broken links etc.

@jenshnielsen
Copy link
Member Author

This takes me down to 43 Sphinx warnings locally.

Most are related to indentation of block quotes in doc strings

/usr/local/Cellar/python/2.7.8_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib-1.5.x-py2.7-macosx-10.9-x86_64.egg/matplotlib/axes/_axes.py:docstring of matplotlib.axes.Axes.bxp:4: WARNING: Block quote ends without a blank line; unexpected unindent.
/usr/local/Cellar/python/2.7.8_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib-1.5.x-py2.7-macosx-10.9-x86_64.egg/matplotlib/axes/_axes.py:docstring of matplotlib.axes.Axes.contourf:78: WARNING: Block quote ends without a blank line; unexpected unindent.
/usr/local/Cellar/python/2.7.8_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib-1.5.x-py2.7-macosx-10.9-x86_64.egg/matplotlib/axes/_axes.py:docstring of matplotlib.axes.Axes.legend:192: WARNING: Block quote ends without a blank line; unexpected unindent.
/usr/local/Cellar/python/2.7.8_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib-1.5.x-py2.7-macosx-10.9-x86_64.egg/matplotlib/axes/_axes.py:docstring of matplotlib.axes.Axes.pcolorfast:26: WARNING: Block quote ends without a blank line; unexpected unindent.
/usr/local/Cellar/python/2.7.8_1/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages/matplotlib-1.5.x-py2.7-macosx-10.9-x86_64.egg/matplotlib/axes/_axes.py:docstring of matplotlib.axes.Axes.set_autoscalex_on:3: WARNING: Block quote ends without a blank line; unexpected unindent.
[u'boxplot_stats(X, whis=1.5, bootstrap=None, labels=None)', u':module: matplotlib.cbook', u'', u'', u'', u'Returns list of dictionaries of staticists to be use to draw a series of', u'box and whisker plots. See the `Returns` section below to the required', u'keys of the dictionary. Users can skip this function and pass a user-', u'defined set of dictionaries to the new `axes.bxp` method instead of', u'relying on MPL to do the calcs.', u'', u'', u':Parameters:', u'', u'    **X** : array-like', u'', u'        Data that will be represented in the boxplots. Should have 2 or fewer', u'        dimensions.', u'        ', u'', u'    **whis** : float, string, or sequence (default = 1.5)', u'', u'        As a float, determines the reach of the whiskers past the first and', u'        third quartiles (e.g., Q3 + whis*IQR, QR = interquartile range, Q3-Q1).', u'        Beyond the whiskers, data are considered outliers and are plotted as', u'        individual points. Set this to an unreasonably high value to force the', u'        whiskers to show the min and max data. Alternatively, set this to an', u'        ascending sequence of percentile (e.g., [5, 95]) to set the whiskers', u'        at specific percentiles of the data. Finally, can  `whis` be the', u"        string 'range' to force the whiskers to the min and max of the data.", u'        In the edge case that the 25th and 75th percentiles are equivalent,', u"        `whis` will be automatically set to 'range'", u'        ', u'', u'    **bootstrap** : int or None (default)', u'', u'        Number of times the confidence intervals around the median should', u'        be bootstrapped (percentile method).', u'        ', u'', u'    **labels** : sequence', u'', u'        Labels for each dataset. Length must be compatible with dimensions', u'        of `X`', u'', u':Returns:', u'', u'    **bxpstats** : list of dict', u'', u'        A list of dictionaries containing the results for each column', u'        of data. Keys of each dictionary are the following:', u'        ', u'        ========   ===================================', u'        Key        Value Description', u'        ========   ===================================', u'        label      tick label for the boxplot', u'        mean       arithemetic mean value', u'        median     50th percentile', u'        q1         first quartile (25th percentile)', u'        q3         third quartile (75th percentile)', u'        cilo       lower notch around the median', u'        ciho       upper notch around the median', u'        whislo     end of the lower whisker', u'        whishi     end of the upper whisker', u'        fliers     outliers', u'        ========   ===================================', u'', u'.. rubric:: Notes', u'', u'', u'Non-bootstrapping approach to confidence interval uses Gaussian-based', u'asymptotic approximation:', u'', u'.. math::', u'', u'    \\mathrm{med} \\pm 1.57 \\times \\frac{\\mathrm{iqr}}{\\sqrt{N}}', u'', u'General approach from:', u'McGill, R., Tukey, J.W., and Larsen, W.A. (1978) "Variations of', u'    Boxplots", The American Statistician, 32:12-16.']:72: ERROR: Unexpected indentation.
[u"deprecated(since, message=u'', name=u'', alternative=u'', pending=False, obj_type=u'function')", u':module: matplotlib.cbook', u'', u'', u'', u'Decorator to mark a function as deprecated.', u'', u'', u':Parameters:', u'', u'    **since** : str', u'', u'        The release at which this API became deprecated.  This is', u'        required.', u'        ', u'', u'    **message** : str, optional', u'', u'        Override the default deprecation message.  The format', u'        specifier `%(func)s` may be used for the name of the function,', u'        and `%(alternative)s` may be used in the deprecation message', u'        to insert the name of an alternative to the deprecated', u'        function.  `%(obj_type)` may be used to insert a friendly name', u'        for the type of object being deprecated.', u'        ', u'', u'    **name** : str, optional', u'', u'        The name of the deprecated function; if not provided the name', u'        is automatically determined from the passed in function,', u'        though this is useful in the case of renamed functions, where', u'        the new function is just assigned to the name of the', u'        deprecated function.  For example::', u'        ', u'            def new_function():', u'                ...', u'            oldFunction = new_function', u'        ', u'', u'    **alternative** : str, optional', u'', u'        An alternative function that the user may use in place of the', u'        deprecated function.  The deprecation warning will tell the user about', u'        this alternative if provided.', u'        ', u'', u'    **pending** : bool, optional', u'', u'        If True, uses a PendingDeprecationWarning instead of a', u'        DeprecationWarning.', u'', u'.. rubric:: Examples', u'', u'', u"@deprecated('1.4.0')", u'def the_function_to_deprecate():', u'    pass']:48: ERROR: Unexpected indentation.

In addition there are some related to the auto generated github_stats.rst

@jenshnielsen
Copy link
Member Author

Unfortunately Travis still has some additional issues and this has only reduced the number of warnings from 894 to 860. Looks like there is an issue with the images not being generated. Looking at the log I guess that the build tries to use an interactive backend which fails.

@@ -13,3 +13,4 @@ Contents:
set_up_fork
configure_git
development_workflow
dot2_dot3
Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do we want to include this or should the file just be deleted/ignored?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It seems useful, but I don't know where to fit it in. We should probably have a 'git magic' page for useful git incantations that we use semi-regularly (such as cherry-picking directions).

@@ -70,13 +70,13 @@ in addition to

In case Python is not installed for all users (not the default), the
Microsoft Visual C++ 2008 (
`64 bit <http://www.microsoft.com/download/en/details.aspx?id=15336>`_
`64 bit <http://www.microsoft.com/download/en/details.aspx?id=15336>`__
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

why the double __?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sphinx warns because both 32 bit and 64 bit are used as labels twice. This changes them to anonymous hyperlink reference which don't have this issue. We don't need to reference these links other places in the docs.

@tacaswell tacaswell modified the milestones: v1.4.1, v1.4.0 Sep 3, 2014
@NelleV
Copy link
Member

NelleV commented Sep 11, 2014

This looks good to me.

@jenshnielsen
Copy link
Member Author

I will move the git section. Arter that it should be ready to merge

tacaswell added a commit that referenced this pull request Sep 13, 2014
DOC : This fixes a bunch of Sphinx warnings
@tacaswell tacaswell merged commit e70c567 into matplotlib:v1.4.0-doc Sep 13, 2014
@tacaswell
Copy link
Member

On consideration, I think the section on git diffs is fine where it is for now.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

4 participants