Numpy's Sphinx extensions

Related tags

Documentation numpydoc
Overview
https://travis-ci.org/numpy/numpydoc.png?branch=master

numpydoc -- Numpy's Sphinx extensions

This package provides the numpydoc Sphinx extension for handling docstrings formatted according to the NumPy documentation format. The extension also adds the code description directives np:function, np-c:function, etc.

numpydoc requires Python 3.5+ and sphinx 1.6.5+.

For usage information, please refer to the documentation.

The numpydoc docstring guide explains how to write docs formatted for this extension, and the user guide explains how to use it with Sphinx.

Comments
  • Sphinx 2.0 compatibility issue?

    Sphinx 2.0 compatibility issue?

    My readthedocs project has started failing to render my docs according to the numpydoc (v0.9.1) layout.

    E.g. this is how my docs looked a couple of months ago:

    image

    And now my docs build to this:

    image

    It appears that this is concurrent with RTD upgrading its sphinx version from 1.8 to 2.0. Is this possibly the culprit? I am not sure how best to proceed in debugging this, so any guidance would be very much appreciated!

    bug 
    opened by rsokl 45
  • Format attributes like parameters

    Format attributes like parameters

    Resolves #102. Resolves #104. Resolves https://github.com/scikit-learn/scikit-learn/issues/9495

    • Provide links to autogen when possible
    • Use fake (commented) autosummary nodes (as already used in scipy docs)

    I'm a bit confused about how/whether the autosummaries inside numpydoc-munged docstrings work. I'm not quite sure whether this patch is working on scipy docs and would appreciate someone checking. It's good for scikit-learn.

    maintenance 
    opened by jnothman 37
  • Add cross-reference links to parameter types

    Add cross-reference links to parameter types

    Tokens of the type description that are determined to be "link-worthy" are enclosed in a new role called xref_param_type. This role when when processed adds a pending_xref node to the DOM. If these types cross-references are not resolved when the build ends, sphinx does not complain. This forgives errors made when deciding whether tokens are "link-worthy". And provided text from the type description is not lost in the processing, the only unwanted outcome is a type link (due to coincidence) when none was desired.

    Added two options:

    1. numpydoc_xref_param_type
    2. numpydoc_xref_aliases

    closes #57

    enhancement 
    opened by has2k1 30
  • Add docstring validation script (from pandas)

    Add docstring validation script (from pandas)

    xref #213

    Updated the pandas validation script to be generic. To validate all docstrings of a project will probably require some work, to consider how the rst lists all public objects.

    Removed from the original script, the next pandas-only features:

    • Setting max_open_warning setting from matplotlib
    • PEP-8 validation of examples (will add in a follow up, but will require a dependency, and also pandas auto-imports modules, and requires updating many docstrings in the tests
    • Check to see if numpy or pandas where imported in the examples
    • Check to see if docstrings mentioned private classes (in pandas NDFrame)
    • GitHub link in the json report
    • Changed pprint_thing by str when rendering the wrong parameter error message
    • Source file in report is not relative to pandas path
    • Methods validated by introspecting Series and DataFrame (besides the ones obtained from the API rst

    Tried with a scikit-learn class and it runs the validation correctly:

    ################################################################################
############## Docstring (sklearn.linear_model.LinearRegression)  ##############
################################################################################

Ordinary least squares Linear Regression.

Parameters
----------
fit_intercept : boolean, optional, default True
    whether to calculate the intercept for this model. If set
    to False, no intercept will be used in calculations
    (e.g. data is expected to be already centered).

normalize : boolean, optional, default False
    This parameter is ignored when ``fit_intercept`` is set to False.
    If True, the regressors X will be normalized before regression by
    subtracting the mean and dividing by the l2-norm.
    If you wish to standardize, please use
    :class:`sklearn.preprocessing.StandardScaler` before calling ``fit`` on
    an estimator with ``normalize=False``.

copy_X : boolean, optional, default True
    If True, X will be copied; else, it may be overwritten.

n_jobs : int, optional, default 1
    The number of jobs to use for the computation.
    If -1 all CPUs are used. This will only provide speedup for
    n_targets > 1 and sufficient large problems.

Attributes
----------
coef_ : array, shape (n_features, ) or (n_targets, n_features)
    Estimated coefficients for the linear regression problem.
    If multiple targets are passed during the fit (y 2D), this
    is a 2D array of shape (n_targets, n_features), while if only
    one target is passed, this is a 1D array of length n_features.

intercept_ : array
    Independent term in the linear model.

Notes
-----
From the implementation point of view, this is just plain Ordinary
Least Squares (scipy.linalg.lstsq) wrapped as a predictor object.

################################################################################
################################## Validation ##################################
################################################################################

6 Errors found:
	Closing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)
	Double line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstrings
	Parameter "fit_intercept" type should use "bool" instead of "boolean"
	Parameter "fit_intercept" description should start with a capital letter
	Parameter "normalize" type should use "bool" instead of "boolean"
	Parameter "copy_X" type should use "bool" instead of "boolean"
3 Warnings found:
	No extended summary found
	See Also section not found
	No examples section found
    enhancement 
    opened by datapythonista 27
  • DOC: Switch docs to pydata-sphinx-theme

    DOC: Switch docs to pydata-sphinx-theme

    NumPy recently switched to the pydata-sphinx-theme for its documentation. The new theme is now deployed for the stable docs as of v1.20. This PR switches the themes so numpydoc's documentation theme is consistent with numpy's.

    enhancement maintenance 
    opened by rossbar 24
  • BUG: Reference de-duplication isn't parallel-safe

    BUG: Reference de-duplication isn't parallel-safe

    Currently Numpydoc is marked as a parallel-safe sphinx plugin, but the renaming of duplicate references in rename_references is not parallel-safe because reference_offset will be [0] in each process at the start of the function call.

    I'm running into conflicts when building the Astropy docs:

    /Users/tom/Dropbox/Code/Astropy/astropy/astropy/stats/biweight.py:docstring of astropy.stats.biweight_midcorrelation:70: WARNING: duplicate citation R11, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/modeling/index.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/stats/biweight.py:docstring of astropy.stats.biweight_midcovariance:138: WARNING: duplicate citation R33, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.coordinates.BaseCoordinateFrame.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/stats/biweight.py:docstring of astropy.stats.biweight_midvariance:101: WARNING: duplicate citation R56, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.coordinates.EarthLocation.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/stats/biweight.py:docstring of astropy.stats.biweight_midvariance:103: WARNING: duplicate citation R66, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.coordinates.EarthLocation.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/stats/bayesian_blocks.py:docstring of astropy.stats.FitnessFunc:7: WARNING: Unknown target name: "scargle2012".
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/stats/bayesian_blocks.py:docstring of astropy.stats.FitnessFunc:26: WARNING: Unknown target name: "scargle2012".
docstring of astropy.stats.LombScargle.false_alarm_probability:62: WARNING: duplicate citation R1313, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.coordinates.SkyCoord.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/modeling/polynomial.py:docstring of astropy.modeling.polynomial.SIP:55: WARNING: duplicate citation R11, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.stats.biweight_midcorrelation.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/modeling/functional_models.py:docstring of astropy.modeling.functional_models.AiryDisk2D:91: WARNING: duplicate citation R11, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.stats.biweight_midcorrelation.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/modeling/functional_models.py:docstring of astropy.modeling.functional_models.Gaussian2D:133: WARNING: duplicate citation R33, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.stats.biweight_midcovariance.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/modeling/optimizers.py:docstring of astropy.modeling.optimizers.SLSQP:19: WARNING: duplicate citation R99, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.coordinates.Galactic.rst
/Users/tom/Dropbox/Code/Astropy/astropy/astropy/modeling/optimizers.py:docstring of astropy.modeling.optimizers.Simplex:18: WARNING: duplicate citation R1111, other instance in /Users/tom/Dropbox/Code/Astropy/astropy/docs/api/astropy.stats.LombScargle.rst
    bug needs-work needs-decision 
    opened by astrofrog 22
  • ENH: Xref param type

    ENH: Xref param type

    Takes over and closes #150 with:

    • [x] rebase
    • [x] fixing tests
    • [x] changing into opt-in behavior
    • [x] ~~fix rendering bugs~~Rendering bugs were a sphinx issue https://github.com/sphinx-doc/sphinx/issues/5959
    • [x] add hint about CSS styles for uniformity.
    enhancement 
    opened by larsoner 21
  • Validation is not strict enough

    Validation is not strict enough

    The docs suggest that python -m numpydoc can be used to validate docstrings. However, numpydoc reports only the most egregious breakages of the standard.

    If we want to help users write high quality docstrings, we should provide a stronger checker.

    In the following example, only the incorrect header gets caught:

    def foo(x):
    """The first line should be a one line description, not a multiple
    paragraph sentence.

    References
    ----------
    These are out of place and incorrectly formatted.

    Some Heading
    ------------
    Unknown heading

    Parameters
    ----------
    x :
    I should specify a type for this parameter

    """
    return x
    opened by stefanv 20
  • Release?

    Release?

    It's been over a year since the last release. I would like to use recent changes in scikit-learn, and it looks like numpy too is being built on the latest release, not on master. Could we more generally plan half-yearly releases or something, even if they're quite small?

    opened by jnothman 20
  • Ensure reference renaming is parallel-safe

    Ensure reference renaming is parallel-safe

    Fixes #112. Builds upon #135. Makes #130 (breaking table whitespace) worse, but see below.

    Also fixes #114

    At autodoc-process-docstring time, this prefixes each reference with a token indicative of which docstring it belongs to and then relabels the text of the reference in the doctree once the reST is parsed. The rendered reference naming therefore reflects what was in the original reST, rather than something with prefixes etc. So you get [1] rather than [R1].

    I'm not sure how to rigorously test this but will post some images soon.

    The issue of breaking table whitespace (#130) is more minor than #112. It is exacerbated by this patch since references become much longer. There may be a more ideal solution that involves post-processing the doctrees to do all of the reference renaming (i.e. without this decorate-and-undecorate approach), but when I tried to implement it, I realised it would involve hacking footnotes to become citations, handling initial broken resolutions (incl docutils.nodes.problematic), and other madness. It may come later. In the meantime I think we should just tell users that citations cannot be used in tables.

    needs-decision 
    opened by jnothman 18
  • Render numpydoc strings from a template

    Render numpydoc strings from a template

    In scikit-learn, we would like to start tracking the upstream numpydoc (https://github.com/scikit-learn/scikit-learn/pull/7355). However, we currently render Attributes closely after Parameters, due to their significance, etc. Numpydoc renders Attributes after examples, notes, references, etc. which we find unideal.

    This patch allows us to add templates/numpydoc_doscstring.rst containing:

    {{index}}
{{summary}}
{{extended_summary}}
{{parameters}}
{{returns}}
{{yields}}
{{other_parameters}}
{{attributes}}
{{raises}}
{{warns}}
{{warnings}}
{{see_also}}
{{notes}}
{{references}}
{{examples}}
{{methods}}

    to achieve the sought reordering. It is clearly also much more flexible than that, but I do not have (many) grand designs as yet.

    enhancement 
    opened by jnothman 18
  • Change PR06 logic to only fail when type is used standalone

    Change PR06 logic to only fail when type is used standalone

    Closes https://github.com/numpy/numpydoc/issues/446

    This is a draft PR for addressing https://github.com/numpy/numpydoc/issues/446 which hasn't yet been discussed. For reviewing, I'd pay special attention to how I went the logic in validate.py, especially the regex.

    opened by amoeba 0
  • PR06 fails when offending type name is used only as a substring

    PR06 fails when offending type name is used only as a substring

    I'm implementing numpydoc validation in my codebase and I have a case where I want to document a parameter like so,

        my_param : SubtringMatcher
    Full script example 
    def my_fun(my_arg):
    """
    A function to test numpydoc behavior.

    This just tests out numpydoc checks for PR06.

    Parameters
    ----------
    my_arg : MyCustomSubstringClass
        My description goes here.

    See Also
    --------
    my_other_fun : Another fun I wrote.
    
    Examples
    --------
    arg = MyCustomSubstringClass("test")
    my_fun(arg)
    """
    pass

    This fails with:

    $ python -m numpydoc --validate script.my_fun
script.my_fun:PR06:Parameter "my_arg" type should use "str" instead of "string"

    Would the project be open to changing how that validation works so PR06 only fails when an offending type name is used all by itself rather than as a substring in a custom type name?

    opened by amoeba 1
  • Italicize type-only values in `Returns` section

    Italicize type-only values in `Returns` section

    type-only values as in

    Returns
-------
int

    should be in italics for consistency with the parameter_name : int style, where int would be in italics.

    Possible reason not to do this: "type-only" is just a convention and it could also be "name-only" and numpydoc wants to stay agnostic on this. If this is the case, feel free to close.

    opened by KendrickLamarck 0
  • Trailing underscores in types

    Trailing underscores in types

    Trailing underscores in types in the Parameters and Returns sections have to be escaped in order to not give an Unknown target name warning.

    Examples that DON'T work :

    def identity(object_):
    """Identity function.

    Parameters
    ----------
    object_ : Any

    Returns
    -------
    object_ : type(object_)
        Just `object_` again.
    """
    return object_

    The returns section

    Returns
-------
type(object_)
    Just `object_` again.

    Without a name doesn't work either. In both cases, I have to write type(object\_).

    I don't know if this is fixable like it was for parameter names (#63). I guess types are actually supposed to be links sometimes, in contrast to parameter names? Feel free to close if that is the case and there's just not really a possible fix.

    opened by KendrickLamarck 2
  • style of `[1]` is strange in numpydoc docs

    style of `[1]` is strange in numpydoc docs

    See https://numpydoc.readthedocs.io/en/latest/format.html#id8

    image

    Here obviously, the left and right brackets have different styles - different colors and different text sizes.

    opened by njzjz 2
  • Add validation for optional parameters

    Add validation for optional parameters

    This PR adds validation check for optional parameters. If an optional parameter exists in the signature of a function, the documentation is checked for one of three options in the 'type':

    1. Use of optional
    2. Use of default
    3. Use of {'option1', 'option2'}

    Related to #367.

    opened by MatthewFlamm 2
Releases(v1.5.0)

  • v1.5.0(Oct 8, 2022)

    What's Changed

    • DOC: Add theme switcher and default to lightmode. by @rossbar in https://github.com/numpy/numpydoc/pull/414
    • Update GH actions by @jarrodmillman in https://github.com/numpy/numpydoc/pull/416
    • ENH: Add support for dict show_inherited_class_members by @larsoner in https://github.com/numpy/numpydoc/pull/415
    • Update precommit linters by @jarrodmillman in https://github.com/numpy/numpydoc/pull/417
    • docs: fix validation include line numbers by @thatlittleboy in https://github.com/numpy/numpydoc/pull/418
    • Require sphinx>=4.2 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/411
    • Require sphinx>=4.2 (cleanup) by @jarrodmillman in https://github.com/numpy/numpydoc/pull/421
    • Remove numpydoc_use_blockquotes by @jarrodmillman in https://github.com/numpy/numpydoc/pull/422
    • DOC: Use :ref: when referring to section headers by @namurphy in https://github.com/numpy/numpydoc/pull/424
    • ENH: Update validate.py to allow parameters with trailing underscores. by @stefmolin in https://github.com/numpy/numpydoc/pull/425
    • BUG: Fix returns parsing no name by @rossbar in https://github.com/numpy/numpydoc/pull/429
    • Use requirements/*.txt files for CI by @jarrodmillman in https://github.com/numpy/numpydoc/pull/435
    • Use Python 3.10 to build docs by @jarrodmillman in https://github.com/numpy/numpydoc/pull/436
    • Update precommit hooks by @jarrodmillman in https://github.com/numpy/numpydoc/pull/437
    • Add cached property support by @rossbar in https://github.com/numpy/numpydoc/pull/433
    • Fix front page by @jarrodmillman in https://github.com/numpy/numpydoc/pull/434
    • Support Python 3.11 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/438
    • Update pydata-sphinx-theme by @jarrodmillman in https://github.com/numpy/numpydoc/pull/440
    • Update doc requirements by @jarrodmillman in https://github.com/numpy/numpydoc/pull/441

    New Contributors

    • @thatlittleboy made their first contribution in https://github.com/numpy/numpydoc/pull/418
    • @namurphy made their first contribution in https://github.com/numpy/numpydoc/pull/424
    • @stefmolin made their first contribution in https://github.com/numpy/numpydoc/pull/425

    Full Changelog: https://github.com/numpy/numpydoc/compare/v1.4.0...v1.5.0

    Source code(tar.gz)
    Source code(zip)

  • v1.5.0rc1(Oct 4, 2022)

    What's Changed

    • DOC: Add theme switcher and default to lightmode. by @rossbar in https://github.com/numpy/numpydoc/pull/414
    • Update GH actions by @jarrodmillman in https://github.com/numpy/numpydoc/pull/416
    • ENH: Add support for dict show_inherited_class_members by @larsoner in https://github.com/numpy/numpydoc/pull/415
    • Update precommit linters by @jarrodmillman in https://github.com/numpy/numpydoc/pull/417
    • docs: fix validation include line numbers by @thatlittleboy in https://github.com/numpy/numpydoc/pull/418
    • Require sphinx>=4.2 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/411
    • Require sphinx>=4.2 (cleanup) by @jarrodmillman in https://github.com/numpy/numpydoc/pull/421
    • Remove numpydoc_use_blockquotes by @jarrodmillman in https://github.com/numpy/numpydoc/pull/422
    • DOC: Use :ref: when referring to section headers by @namurphy in https://github.com/numpy/numpydoc/pull/424
    • ENH: Update validate.py to allow parameters with trailing underscores. by @stefmolin in https://github.com/numpy/numpydoc/pull/425
    • BUG: Fix returns parsing no name by @rossbar in https://github.com/numpy/numpydoc/pull/429
    • Use requirements/*.txt files for CI by @jarrodmillman in https://github.com/numpy/numpydoc/pull/435
    • Use Python 3.10 to build docs by @jarrodmillman in https://github.com/numpy/numpydoc/pull/436
    • Update precommit hooks by @jarrodmillman in https://github.com/numpy/numpydoc/pull/437
    • Add cached property support by @rossbar in https://github.com/numpy/numpydoc/pull/433
    • Fix front page by @jarrodmillman in https://github.com/numpy/numpydoc/pull/434
    • Support Python 3.11 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/438

    New Contributors

    • @thatlittleboy made their first contribution in https://github.com/numpy/numpydoc/pull/418
    • @namurphy made their first contribution in https://github.com/numpy/numpydoc/pull/424
    • @stefmolin made their first contribution in https://github.com/numpy/numpydoc/pull/425

    Full Changelog: https://github.com/numpy/numpydoc/compare/v1.4.0...v1.5.0rc1

    Source code(tar.gz)
    Source code(zip)

  • v1.4.0(Jun 9, 2022)

    What's Changed

    • Use black by @jarrodmillman in https://github.com/numpy/numpydoc/pull/391
    • Ignore black formatting by @jarrodmillman in https://github.com/numpy/numpydoc/pull/394
    • Test on 3.11 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/375
    • Update pre-commit by @jarrodmillman in https://github.com/numpy/numpydoc/pull/396
    • Cleanup sphinx conf by @jarrodmillman in https://github.com/numpy/numpydoc/pull/397
    • Remove old warning filters by @jarrodmillman in https://github.com/numpy/numpydoc/pull/398
    • Fix bug with version name by @jarrodmillman in https://github.com/numpy/numpydoc/pull/400
    • Test prereleases of requirements by @jarrodmillman in https://github.com/numpy/numpydoc/pull/395
    • Add workaround for pytest failures on 3.11b2 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/404
    • Use node.findall if available (docutils 18.x) by @drammock in https://github.com/numpy/numpydoc/pull/403
    • Test docutils 0.18.1 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/402
    • Update GH actions by @jarrodmillman in https://github.com/numpy/numpydoc/pull/406
    • Fix CI by @jarrodmillman in https://github.com/numpy/numpydoc/pull/410
    • Remove pytest py3.11b2 workaround by @jarrodmillman in https://github.com/numpy/numpydoc/pull/407

    New Contributors

    • @drammock made their first contribution in https://github.com/numpy/numpydoc/pull/403

    Full Changelog: https://github.com/numpy/numpydoc/compare/v1.3.1...v1.4.0

    Source code(tar.gz)
    Source code(zip)

  • v1.4.0rc1(Jun 8, 2022)

    What's Changed

    • Use black by @jarrodmillman in https://github.com/numpy/numpydoc/pull/391
    • Ignore black formatting by @jarrodmillman in https://github.com/numpy/numpydoc/pull/394
    • Test on 3.11 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/375
    • Update pre-commit by @jarrodmillman in https://github.com/numpy/numpydoc/pull/396
    • Cleanup sphinx conf by @jarrodmillman in https://github.com/numpy/numpydoc/pull/397
    • Remove old warning filters by @jarrodmillman in https://github.com/numpy/numpydoc/pull/398
    • Fix bug with version name by @jarrodmillman in https://github.com/numpy/numpydoc/pull/400
    • Test prereleases of requirements by @jarrodmillman in https://github.com/numpy/numpydoc/pull/395
    • Add workaround for pytest failures on 3.11b2 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/404
    • Use node.findall if available (docutils 18.x) by @drammock in https://github.com/numpy/numpydoc/pull/403
    • Test docutils 0.18.1 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/402
    • Update GH actions by @jarrodmillman in https://github.com/numpy/numpydoc/pull/406

    New Contributors

    • @drammock made their first contribution in https://github.com/numpy/numpydoc/pull/403

    Full Changelog: https://github.com/numpy/numpydoc/compare/v1.3.1...v1.4.0rc1

    Source code(tar.gz)
    Source code(zip)

  • v1.3.1(Apr 30, 2022)

    What's Changed

    • Update doc requirements by @jarrodmillman in https://github.com/numpy/numpydoc/pull/389
    • Update manifest by @jarrodmillman in https://github.com/numpy/numpydoc/pull/388

    Full Changelog: https://github.com/numpy/numpydoc/compare/v1.3.0...v1.3.1

    Source code(tar.gz)
    Source code(zip)

  • v1.3.0(Apr 29, 2022)

    Requires Python 3.7+ and Sphinx 3.0+.

    What's Changed

    • Remove deprecated numpydoc_edit_link by @jarrodmillman in https://github.com/numpy/numpydoc/pull/372
    • Cleanup cruft by @jarrodmillman in https://github.com/numpy/numpydoc/pull/371
    • Add pre-commit hook / linter by @jarrodmillman in https://github.com/numpy/numpydoc/pull/374
    • DOC: fix broken link to built-in validation checks. by @rossbar in https://github.com/numpy/numpydoc/pull/379
    • Runtime verification of sphinx and jinja2 versions by @rossbar in https://github.com/numpy/numpydoc/pull/381
    • MAINT: Dont import for version by @larsoner in https://github.com/numpy/numpydoc/pull/382
    • Update tests + coverage config to rm warnings. by @rossbar in https://github.com/numpy/numpydoc/pull/383
    • Require sphinx>3 by @jarrodmillman in https://github.com/numpy/numpydoc/pull/385

    Full Changelog: https://github.com/numpy/numpydoc/compare/v1.2.1...v1.3.0

    Source code(tar.gz)
    Source code(zip)

  • v1.3rc1(Apr 25, 2022)

  • v1.2.1(Mar 29, 2022)

    Requires Python 3.7+ and Sphinx 1.8+.

    Full Changelog

    Implemented enhancements

    Fixed bugs

    Closed issues

    • Validation check YD01 not implemented properly #365
    • Support numpydoc validation without running sphinx #364
    • 1.2: change tagging convention? #360
    Source code(tar.gz)
    Source code(zip)

  • numpydoc-1.2(Jan 24, 2022)

    Requires Python 3.7+ and Sphinx 1.8+.

    Implemented enhancements

    Fixed bugs

    • How to specify that parameter can equal the string 'integer'? #341
    • Fix validation bug when parameter type is set of options. #347 (rossbar)
    • Escape newline in docstring. #345 (Carreau)
    • Correctly validate parameters under the "Other Parameters" section #337 (dcbr)
    • BUG: fix an incomplete check in Reader.\_error\_location #308 (rgommers)
    • MAINT: pytest ignore doc directory. #296 (rossbar)
    • DOC: fix inaccuracy in validate docstring. #294 (rossbar)
    • Fix param parsing. #286 (Carreau)
    • BUG: Properly parse See Also when summary on first line. #283 (Carreau)
    • BUG: fix role regex. #280 (Carreau)
    • fix splitting of parameter lines. #279 (Carreau)

    Closed issues

    • Class methods (@classmethod) are not documented using numpydoc #340
    • Exclude certain methods from METHODS section #338
    • Warnings is not allowed in "GL06" check #334
    • Add version to style guide #333
    • numpydoc does not render parameters as expected #329
    • 1.1.0: pytest warnings #324
    • RTD configuration - latest #321
    • Rendering of types in latest doc build #318
    • Anchors for individual sections in numpydoc doc? #317
    • Development documentation not up-to-date #311
    • Warning: autosummary: stub file not found #290
    • Wrong number of Parameter for numpy array. #285
    • syntax to document default values #284
    • Failed See Also Parsing. #281
    • Sphinx emits "WARNING: py:class reference target not found" with numpydoc 1.1.0 #275
    Source code(tar.gz)
    Source code(zip)

  • numpydoc-1.2rc1(Jan 21, 2022)

  • v1.1.0(Jul 1, 2020)

    Implemented enhancements

    • MAINT: Suggestions from reviewing test suite #271 <https://github.com/numpy/numpydoc/pull/271>__ (rossbar <https://github.com/rossbar>__)
    • DEV: Add testing requirements #267 <https://github.com/numpy/numpydoc/pull/267>__ (rossbar <https://github.com/rossbar>__)
    • BUG: Defer to autodoc for signatures #221 <https://github.com/numpy/numpydoc/pull/221>__ (thequackdaddy <https://github.com/thequackdaddy>__)

    Fixed bugs

    • function signatures for *args, **kwargs objects off #218 <https://github.com/numpy/numpydoc/issues/218>__
    • BUG: Connect to earlier event #269 <https://github.com/numpy/numpydoc/pull/269>__ (larsoner <https://github.com/larsoner>__)

    Closed issues

    • “Handler <function mangle_docstrings at 0x7f64b5ba57b8> for event ‘autodoc-process-docstring’ threw an exception” #268 <https://github.com/numpy/numpydoc/issues/268>__
    • Timing of next release #249 <https://github.com/numpy/numpydoc/issues/249>__
    • self included in list of params for method #220 <https://github.com/numpy/numpydoc/issues/220>__

    Additional notes

    • Due to merging of #221 <https://github.com/numpy/numpydoc/pull/221>__, self and cls no longer will appear in method signatures.
    Source code(tar.gz)
    Source code(zip)

  • v1.0.0(May 26, 2020)

    Implemented enhancements:

    Fixed bugs

    Removed

    • MNT Drop Python 2.7 and 3.4 support #236 (rth)

    Closed issues

    • Prefix added to reference keys in class docstrings #263
    • Test failure with python 3.9 #261
    • sphinx doc napoleon extension maintainer interest request #251
    • Missing reference to float_power function in the ufunc list #250

    Additional notes

    Source code(tar.gz)
    Source code(zip)

  • v0.9.1(Apr 23, 2019)

    This is a bug fix release for 0.9.0 with only one change:

    Merged pull requests:

    • Updating minimum sphinx version in setup.py #211

    Closed issues:

    • AttributeError: 'module' object has no attribute 'getLogger' #210
    Source code(tar.gz)
    Source code(zip)

  • v0.9.0(Apr 21, 2019)

    Implemented enhancements:

    Fixed bugs:

    • References messed up #177
    • BUG?: References always have an errant second link #169
    • BUG: turn member descriptor attributes into links #201 (mattip)
    • FIX: Fix collections.abc imports #195 (larsoner)
    • FIX: Escape chars in re #194 (larsoner)
    • Fix markup in format.rst. #193 (anntzer)
    • Move setup of autosummary earlier in setup(). #191 (anntzer)
    • Only print the index if it is necessary. #187 (hmaarrfk)
    • FIX pedantic handling of whitespace in reference regex #181 (jnothman)
    • FIX remove duplicated citation back-references #180 (jnothman)
    • Use DEDUPLICATION_TAG to determine whether a citation node is in a docstring #179 (jnothman)
    • FIX parsing of type-only return params #175 (timhoffm)
    • pip --use-wheel no longer exists #174 (jnothman)
    • DOC: Add missing backslash to omega for inline math example. #171 (pvanmulbregt)
    • DOC: remove links to numpy repo file #167 (mattip)
    • Escape the * in *args and **kwargs #155 (has2k1)

    Closed issues:

    • autosummary fails with numpydoc where napoleon succeeds #204
    • NumpyDocString doesn't roundtrip well #188
    • Generating a docstring from a numpydoc object #186
    • make parameters and attributes anchors in docstrings #185
    • BUG: Plot(s) not rendered if docstring ends with normal text after show command #162
    • Location reporting returns useless information #115
    • Anonymous return values have their types populated in the name slot of the tuple. #72
    • support for coroutine #47
    • multiple entries in a See Also section #28
    Source code(tar.gz)
    Source code(zip)
Owner
NumPy
NumPy
GitHub https://numpydoc.readthedocs.io/
Numpy's Sphinx extensions

numpydoc -- Numpy's Sphinx extensions This package provides the numpydoc Sphinx extension for handling docstrings formatted according to the NumPy doc

NumPy 234 Dec 26, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 2, 2023
A curated list of awesome tools for Sphinx Python Documentation Generator

Awesome Sphinx (Python Documentation Generator) A curated list of awesome extra libraries, software and resources for Sphinx (Python Documentation Gen

Hyunjun Kim 831 Dec 27, 2022
Main repository for the Sphinx documentation builder

Sphinx Sphinx is a tool that makes it easy to create intelligent and beautiful documentation for Python projects (or other documents consisting of mul

null 5.1k Jan 4, 2023
Sphinx theme for readthedocs.org

Read the Docs Sphinx Theme This Sphinx theme was designed to provide a great reader experience for documentation users on both desktop and mobile devi

Read the Docs 4.3k Dec 31, 2022
ReStructuredText and Sphinx bridge to Doxygen

Breathe Packagers: PGP signing key changes for Breathe >= v4.23.0. https://github.com/michaeljones/breathe/issues/591 This is an extension to reStruct

Michael Jones 643 Dec 31, 2022
Type hints support for the Sphinx autodoc extension

sphinx-autodoc-typehints This extension allows you to use Python 3 annotations for documenting acceptable argument types and return value types of fun

Alex Grönholm 462 Dec 29, 2022
Watch a Sphinx directory and rebuild the documentation when a change is detected. Also includes a livereload enabled web server.

sphinx-autobuild Rebuild Sphinx documentation on changes, with live-reload in the browser. Installation sphinx-autobuild is available on PyPI. It can

Executable Books 440 Jan 6, 2023
sphinx builder that outputs markdown files.

sphinx-markdown-builder sphinx builder that outputs markdown files Please ★ this repo if you found it useful ★ ★ ★ If you want frontmatter support ple

Clay Risser 144 Jan 6, 2023
Sphinx Bootstrap Theme

Sphinx Bootstrap Theme This Sphinx theme integrates the Bootstrap CSS / JavaScript framework with various layout options, hierarchical menu navigation

Ryan Roemer 584 Nov 16, 2022
A powerful Sphinx changelog-generating extension.

What is Releases? Releases is a Python (2.7, 3.4+) compatible Sphinx (1.8+) extension designed to help you keep a source control friendly, merge frien

Jeff Forcier 166 Dec 29, 2022
📖 Generate markdown API documentation from Google-style Python docstring. The lazy alternative to Sphinx.

lazydocs Generate markdown API documentation for Google-style Python docstring. Getting Started • Features • Documentation • Support • Contribution •

Machine Learning Tooling 118 Dec 31, 2022
Seamlessly integrate pydantic models in your Sphinx documentation.

Seamlessly integrate pydantic models in your Sphinx documentation.

Franz Wöllert 71 Dec 26, 2022
Speed up Sphinx builds by selectively removing toctrees from some pages

Remove toctrees from Sphinx pages Improve your Sphinx build time by selectively removing TocTree objects from pages. This is useful if your documentat

Executable Books 8 Jan 4, 2023
python package sphinx template

python-package-sphinx-template python-package-sphinx-template

Soumil Nitin Shah 2 Dec 26, 2022
epub2sphinx is a tool to convert epub files to ReST for Sphinx

epub2sphinx epub2sphinx is a tool to convert epub files to ReST for Sphinx. It uses Pandoc for converting HTML data inside epub files into ReST. It cr

Nihaal 8 Dec 15, 2022
A `:github:` role for Sphinx

sphinx-github-role A github role for Sphinx. Usage Basic usage MyST: :caption: index.md See {github}`astrojuanlu/sphinx-github-role#1`. reStructuredT

Juan Luis Cano Rodríguez 4 Nov 22, 2022
This is a template (starter kit) for writing Maturity Work with Sphinx / LaTeX at Collège du Sud

sphinx-tm-template Ce dépôt est un template de base utilisable pour écrire ton travail de maturité dans le séminaire d'informatique du Collège du Sud.

null 6 Dec 22, 2022
Sphinx-performance - CLI tool to measure the build time of different, free configurable Sphinx-Projects

CLI tool to measure the build time of different, free configurable Sphinx-Projec

useblocks 11 Nov 25, 2022
Numpy's Sphinx extensions

numpydoc -- Numpy's Sphinx extensions This package provides the numpydoc Sphinx extension for handling docstrings formatted according to the NumPy doc

NumPy 234 Dec 26, 2022