[issue16544] Add external link to ast docs
New submission from Andrew Svetlov: http://greentreesnakes.readthedocs.org/en/latest/index.html is excellent and comprehensive documentation for ast tree structures. It would be nice to incorporate that docs into stdlib documentation, but adding *see also* section is good enoigh as first step. ---------- assignee: docs@python components: Documentation keywords: easy messages: 176239 nosy: asvetlov, docs@python priority: normal severity: normal stage: needs patch status: open title: Add external link to ast docs versions: Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Ezio Melotti added the comment: I would suggest to contact the author and ask him if he wants to contribute those docs to Python. They could be then be merged to the current docs or included as a separate HOWTO. ---------- nosy: +ezio.melotti type: -> enhancement _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Andrew Svetlov added the comment: I've done it just now sending him message via bitbucket. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Thomas Kluyver added the comment: Thanks, I'm really glad to see that it's useful to others. I don't mind contributing it to Python, but I wonder if it's better to let it develop separately for a few months first - it's still very new, and I can improve it faster in a repository where I can commit to it myself. I'm open to other opinions on that, though. In the meantime, let me know if there are any specific formats/styles/etc. that I should work towards, to make a later move into the official docs simpler. I have a couple of particular questions: - The repository includes some utility code for exploring ASTs, as well as longer, runnable versions of the examples in the docs. What would be the best way to preserve these? - There are some nodes (like AugLoad) that I've yet to find what they actually do, while I've only seen Param in Python 2. Is this an issue? Of course, you're more than welcome to give a 'see also' link to GTS if we decide not to move it for now. ---------- nosy: +takluyver _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Ezio Melotti added the comment:
I don't mind contributing it to Python, but I wonder if it's better to let it develop separately for a few months first - it's still very new, and I can improve it faster in a repository where I can commit to it myself.
That's fine, there's no hurry to merge this. We should also decide on the approach, e.g.: 1) we could extract bits from your work and use them to improve the current docs (you can also report problems that you might notice in the current docs); 2) we could add your work to the current ast docs; 3) we could add your work as a separate howto in Doc/howto/;
In the meantime, let me know if there are any specific formats/styles/etc.
The general guidelines are explained here: http://docs.python.org/devguide/documenting.html You can also look at the current docs to get an idea.
What would be the best way to preserve these?
If they are not too long they could be kept in the rst files, otherwise they could be included in the Tools/ dir.
Is this an issue?
Any improvement is welcomed -- it doesn't necessarily have to be comprehensive, but it should be correct. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Thomas Kluyver added the comment: I think that putting the full content of GTS into the ast module docs would make it awkwardly long. Perhaps the bulk of it could become a howto, and GTS could be maintained separately as a showcase of examples. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Changes by Berker Peksag <berker.peksag@gmail.com>: ---------- nosy: +berker.peksag _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Carol Willing added the comment: Matthias, I've added you to the nosy list for this ast doc enhancements issue. Reference: msg243484 on Issue 24220. ---------- nosy: +mbussonn, willingc versions: +Python 3.5 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Thomas Kluyver added the comment: Here's a simple patch that links to Green Tree Snakes from the ast module docs, using the 'sidebar' directive (that's what the logging module uses to link to tutorials, which seemed analogous). I'm still happy to contribute these docs to CPython if people want that, but I'm also happy to keep maintaining them as a separate resource. I can see advantages to both approaches. ---------- keywords: +patch Added file: http://bugs.python.org/file39420/link-gts.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- assignee: docs@python -> ezio.melotti versions: +Python 3.6 -Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Roundup Robot added the comment: New changeset 94b0e5e9b6e8 by Senthil Kumaran in branch '3.4': Issue16544 - Add a link to an external documentation resource in ast module docs. https://hg.python.org/cpython/rev/94b0e5e9b6e8 New changeset ebf164b07be1 by Senthil Kumaran in branch '3.5': merge from 3.4 https://hg.python.org/cpython/rev/ebf164b07be1 New changeset 62e88e5a61c0 by Senthil Kumaran in branch 'default': merge from 3.5 https://hg.python.org/cpython/rev/62e88e5a61c0 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
Senthil Kumaran added the comment: Thanks for patch and the work on Green Tree Snakes, Thomas. It is a great resource. I agree that a lot could be included directly in stdlib docs, but till then, as suggested/recommended by Andrew and Ezio, a see also link is a good addition. ---------- assignee: ezio.melotti -> orsenthil nosy: +orsenthil resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue16544> _______________________________________
participants (7)
-
Andrew Svetlov -
Berker Peksag
-
Carol Willing
-
Ezio Melotti
-
Roundup Robot
-
Senthil Kumaran
-
Thomas Kluyver