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
Clean-up turtledemo in-package documentation #54500
Comments
Since after closing of issue bpo-10199, docstrings in demo scripts are accessible to pydoc, it is important to bring them up to date. For example, turtledemo.wikipedia docstring contains a reference to nonexistent wikipedia1 and calls itself tdemo_wikipedia3.py. In addition, the turtledemo package contains three text files: Lib/turtledemo/about_turtle.txt, Lib/turtledemo/about_turtledemo.txt, and Lib/turtledemo/demohelp.txt. The contents of these files should be moved to appropriate (doc)strings inside appropriate .py files. |
Agreed. Which .py files would be appropriate? |
On Tue, Mar 22, 2011 at 2:55 PM, Éric Araujo <report@bugs.python.org> wrote:
Lib/turtledemo/about_turtle.txt - seems to belong to turtle.py Lib/turtledemo/about_turtledemo.txt -> turtledemo/init.py and Lib/turtledemo/demohelp.txt. -> turtledemo/main.py or a new |
On Tue, Mar 22, 2011 at 3:14 PM, Alexander Belopolsky
In fact, it looks like turtle docstring is already a copy (or almost a |
The patch contains one unrelated code change. I think the docstrings should not go as is but be cleaned up to match docstrings conventions. I’ve also spotted some phrasing issues. |
On Tue, Mar 22, 2011 at 5:15 PM, Éric Araujo <report@bugs.python.org> wrote:
Yes, I noticed that, but it may not be that unrelated. Of course the
I would rather keep code and documentation changes separate. Not that |
*looks at ast.py and grumbles* |
On Tue, Mar 22, 2011 at 5:29 PM, Éric Araujo <report@bugs.python.org> wrote:
The text added to docstrings was copied from deleted text files. (I |
Thanks for the bug report and patch, belopolsky! The original patch no longer applies cleanly, so attached is a regenerated version.
There is a lot of out of date content in the turtle docs, and I think we should consider that work separate from this ticket and do a full audit of what needs updating in a new ticket. => commit review |
New changeset 004fe3449193 by Ned Deily in branch 'default': |
Thanks for the refresh, Jessica. I decided to separate out the turtle window raise for OS X and apply that for 3.4.1 and 3.5.0 in bpo-11571. The remainder of the patch to use the docstrings, plus removal of the two other obsolete text files, is spplied here for 3.5.0. |
Is there any reason when turtledemo.__init__ and turtledemo.__main__ should not get docstrings in earlier versions? And the turtledemo.__main__ get the same changes in 3.4? Not doing so introduced seeming gratuitous differences between the versions. The help refactoring I committed in 3.4 for bpo-22053 could not be merged as it is. The demohelp.txt changes I have made for 3.4 have cleanly merged forward to file that is ignored and no longer displayed. With demohelp.txt moved to a docstring for 3.4 also, I would leave demohelp.txt in 3.4 but mark it 'unmaintained. Why was demohelp.txt left after being copied to .__main__? Expecting the file and docstring to remain in sync is not realistic. |
I think my reasoning was that it was not a bug fix so it wasn't a strong candidate for a maintenance release. But feel free to backport it if you think it important.
It wasn't: 004fe3449193 deleted it. It appears that an incorrect merge from 3.4 (3f4abe3107ce) in a subsequent set of changes for bpo-21823 brought it back to life in default. |
Thanks for the explanation. I will re-delete the file after copying 3.4 version to docstring and marking the original .txt as frozen. |
New changeset 7708f80940b0 by Terry Jan Reedy in branch '3.4': New changeset 68902ee48985 by Terry Jan Reedy in branch 'default': |
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: