classification
Title: Add external link to ast docs
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.6, Python 3.5
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: orsenthil Nosy List: asvetlov, berker.peksag, docs@python, ezio.melotti, mbussonn, orsenthil, python-dev, takluyver, willingc
Priority: normal Keywords: easy, patch

Created on 2012-11-23 20:20 by asvetlov, last changed 2016-01-07 05:34 by orsenthil. This issue is now closed.

Files
File name Uploaded Description Edit
link-gts.patch takluyver, 2015-05-18 17:17 review
Messages (10)
msg176239 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-23 20:20
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.
msg176240 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-23 20:23
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.
msg176250 - (view) Author: Andrew Svetlov (asvetlov) * (Python committer) Date: 2012-11-23 20:36
I've done it just now sending him message via bitbucket.
msg176285 - (view) Author: Thomas Kluyver (takluyver) * Date: 2012-11-24 13:10
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.
msg176319 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-11-24 20:46
> 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.
msg176322 - (view) Author: Thomas Kluyver (takluyver) * Date: 2012-11-24 23:07
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.
msg243486 - (view) Author: Carol Willing (willingc) * (Python committer) Date: 2015-05-18 15:02
Matthias, I've added you to the nosy list for this ast doc enhancements issue. Reference: msg243484 on Issue 24220.
msg243499 - (view) Author: Thomas Kluyver (takluyver) * Date: 2015-05-18 17:17
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.
msg257671 - (view) Author: Roundup Robot (python-dev) (Python triager) Date: 2016-01-07 05:31
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
msg257672 - (view) Author: Senthil Kumaran (orsenthil) * (Python committer) Date: 2016-01-07 05:34
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.
History
Date User Action Args
2016-01-07 05:34:32orsenthilsetstatus: open -> closed

assignee: ezio.melotti -> orsenthil

nosy: + orsenthil
messages: + msg257672
resolution: fixed
stage: needs patch -> resolved
2016-01-07 05:31:20python-devsetnosy: + python-dev
messages: + msg257671
2016-01-02 08:25:36ezio.melottisetassignee: docs@python -> ezio.melotti
versions: + Python 3.6, - Python 3.3, Python 3.4
2015-05-18 17:17:06takluyversetfiles: + link-gts.patch
keywords: + patch
messages: + msg243499
2015-05-18 15:02:39willingcsetnosy: + willingc, mbussonn

messages: + msg243486
versions: + Python 3.5
2015-05-18 13:44:56berker.peksagsetnosy: + berker.peksag
2012-11-24 23:07:52takluyversetmessages: + msg176322
2012-11-24 20:46:51ezio.melottisetmessages: + msg176319
2012-11-24 13:10:40takluyversetnosy: + takluyver
messages: + msg176285
2012-11-23 20:36:54asvetlovsetmessages: + msg176250
2012-11-23 20:23:46ezio.melottisettype: enhancement

messages: + msg176240
nosy: + ezio.melotti
2012-11-23 20:20:32asvetlovcreate