Skip to content

Addition to the docstring standard: an optional section for noting deprecation (Trac #1501) #2098

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
Closed
thouis opened this issue Oct 19, 2012 · 10 comments
Closed

Addition to the docstring standard: an optional section for noting deprecation (Trac #1501) #2098

thouis opened this issue Oct 19, 2012 · 10 comments
Labels
01 - Enhancement component: documentation
Milestone
(historic) NumPy 2.0

Comments

@thouis
Copy link
Contributor

thouis commented Oct 19, 2012

Original ticket http://projects.scipy.org/numpy/ticket/1501 on 2010-06-03 by trac user dgoldsmith, assigned to @pv.

Presently, the docstring standard does not specify how to note that an object is to be deprecated; it has been proposed that this needs to be rectified.

Obviously, this should be an optional section in general, but required for objects once it is decided that they are to be deprecated.

Discussion on scipy-dev agreed that this section should be at or near the top, but at the top or between the One-line and Extended Summaries have both been proposed - we will try to reach a consensus here.

Proposed format is to utilize Sphinx' .. deprecated:: directive; someone please provide a concrete example of what this looks like (for example, does this directive support multi-line content, and if so, what does that look like).

Proposed content: summaries of deprecation schedule (in version number time, not real time) and justification for deprecation (e.g., being replaced, duplicates extant functionality elsewhere); existing alternatives to obtain the same functionality. (Feel strongly that it should contain something else? Add it below as a comment.)

IMO, we should try to decide on this and update the standard by June 15 at the latest.

Have I forgotten anything?
@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

Attachment added by trac user dgoldsmith on 2010-06-18: HOWTO_DOCUMENT_diff.txt

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

trac user dgoldsmith wrote on 2010-06-18

Fix attached.

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

@rgommers wrote on 2010-06-19

Don't know how you created that patch, but it's not supposed to look like this. You only want to see the lines that changes, not - everything, then + everything.

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

Milestone changed to NumPy 2.0 by @rgommers on 2010-06-19

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

trac user dgoldsmith wrote on 2010-06-20

I think it's a line ending issue. Unfortunately, TortoiseSVN only provides the "ignore line endings" options via the "Merge" and "Blame" commands, not via the "Patch" command, so I'm at a loss...

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

trac user dgoldsmith wrote on 2010-06-24

I posted the following to the tortoisesvn discussion users forum:

Is there a way to ignore line endings when creating a patch?

And got the following reply:

no, but the tools which later apply the patch can do that.

http://tortoisesvn.tigris.org/ds/viewMessage.do?dsForumId=4061&viewType=browseAll&dsMessageId=2623806#messagefocus

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

@scottza wrote on 2010-06-24

Try using a text editor that is aware of line endings to convert the line endings of your edited file to Unix format (e.g. http://notepad-plus-plus.org/ Edit -> EOL Conversion -> Unix format), then create a new patch.

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

Attachment added by trac user dgoldsmith on 2010-06-24: HOWTO_DOCUMENT.patch

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

trac user dgoldsmith wrote on 2010-06-24

Thanks, Scott.

@thouis
Copy link
Contributor Author

thouis commented Oct 19, 2012

@rgommers wrote on 2011-03-29

added section describing this in c2081ae

@thouis thouis closed this as completed Oct 19, 2012
@numpy-gitbot numpy-gitbot mentioned this issue Oct 23, 2012
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
01 - Enhancement component: documentation
Projects
None yet
Milestone
(historic) NumPy 2.0
Development

No branches or pull requests
1 participant
@thouis