Remove our fork of the numpydoc instructions in favor of the official page #9727
Conversation
… numpydoc format page
|
I vote for adding a change log, in case someone links to that page and is confused the link is broken now. Also, are you sure our rules are exactly the same as Numpy's? Did we resolve the "array-like" vs "array_like"? |
|
Failure is real: |
|
@pllim - I think the only actual real difference in rule was I'll fix the doc warning, and I can also add back an orphan page giving the link to the new page in case anyone has linked to the old doc rules from other websites. |
|
Note to maintainers: let's wait for a few other approvals before considering whether to merge this |
| @@ -1,569 +1,8 @@ | |||
| .. doctest-skip-all | |||
| .. _doc-rules: | |||
| :orphan: | |||
There was a problem hiding this comment.
I'm not a big fan of keeping orphan pages. Why not delete it all?
There was a problem hiding this comment.
In case any other projects were linking to it, to avoid breaking links for now.
There was a problem hiding this comment.
I am pretty sure sunpy is linking to this. Nope, maybe not.
There was a problem hiding this comment.
Then they better update their links? 🤷♀
There was a problem hiding this comment.
I have merged this now, but my comment still stands. I don't think we should keep orphaned pages around, downstream should keep track of their links and update as needed.
CHANGES.rst
Outdated
| @@ -335,7 +335,9 @@ astropy.wcs | |||
| Other Changes and Additions | |||
| --------------------------- | |||
|
|
|||
|
|
|||
| - The page in the documentatin describing the astropy docstring rules has now | |||
There was a problem hiding this comment.
I don't think we need any changelog for this.
There was a problem hiding this comment.
typo: "documentation" (if the changelog entry stays there :))
|
Release wise I would be happier with this in 4.0 than in 4.0.1. |
astrofrog
force-pushed
the
numpydoc-docs
branch
from
1540648 to
4f0a679
Compare
|
I removed the changelog entry and re-milestoned to 4.0 |
|
There is overall happiness with 5 approvals, so I go ahead now and merge this. Thank you @astrofrog |
Remove our fork of the numpydoc instructions in favor of the official page
While working on #9726 I noticed that there were a number of out-of-date sections in the docs, one of which was the sentence that mentioned that we ship a fork of numpydoc in astropy. In fact we use vanilla numpydoc and don't bundle it anymore. At the time we set up our docs, the numpydoc format specification was not available on a nicely presented page so we forked them - however, the specification can now be found at https://numpydoc.readthedocs.io/en/latest/format.html which is nice and readable.
Our version has some small differences, mainly a couple of examples where we chose astropy-related variable/type names, but other than that our version is just an out of date version of the official one. So this PR is to propose simply removing our fork in favor of linking to the official one. This will also make it much simpler to stay up to date as the numpydoc package and format grow some new features.
I'm not sure if we need a changelog entry? If people are on board with this, would it make sense to include in 4.0?