Document what APE and Astropy API proposals are

[cdeil]

@astrofrog @eteq @perrygreenfield I couldn't find any info on what the Astropy-APEs and astropy-api proposals are on the Astropy webpage or in the docs.

It would be very nice to have an overview table (similar to the one there is for PEPs that shows some basic info (number, title, status) and links to the document and the discussion, but that is not so easy to auto-generate.

As a start, how about adding a section describing what they are and where to find them here?
http://www.astropy.org/contribute.html

[astrofrog]

👍

[cdeil]

Actually I'm not 100% clear on what the difference between an API proposal and an APE is ... so I'd prefer if one of you writes this paragraph.

Let me explain where I'm coming from and why I'm a bit grumpy today. I've spent a few hours today reading the old discussions and trying to understand the status and plan for coordinates, generalised WCS and ccdproc with the hope to help come up with a good API proposal and plan Brigitta's GSoC work for photutils in the coming weeks.

Most of the open API proposals are one or two years old and have lots of discussions but the document was never updated to reflect those. So coming back to these old discussions is very time-consuming for everyone. Also many of them are just Python files without links to other API or APE documents or issues or pull requests for ongoing or planned actual work, so are less helpful for the group that is supposed to implement it than they could be.

IMO it would be better to only have APEs (i.e. shut down astropy-api).
Even if it is painful now to move the open API documents over, I think in the long-term if will be much simpler to have only one repository where all documents are written in RST, because it will be possible to make a webpage out of those and have a list (instead of two lists).

[eteq]

@cdeil - I agree with you that we should favor APEs over astropy-api. The main thing astropy-api is useful for now that the APEs exist, at least in my mind, is to provide a place to put API proposals in parallel with APEs. But I could also see these actually going in the APE repository instead.

@perrygreenfield or @astrofrog - what do you think about this?

[eteq]

Oh, but I'm definitely 👍 to having this on the site and/or in the docs. Up until now I'd been thinking APE1 is the appropriate reference to understand the where/why/what of APEs, but I see the point that that's rather circular ;)

[cdeil]

I've made an APE overview wiki page.
This is easier to maintain than on the webpage and auto-generating the list is hard (because it would have to inspect open pull requests).

There still should be a sentence or section on the web site explaining what an APE is and linking to that wiki page.

[eteq]

Thanks, @cdeil - #29 now adds a description and links to the APE repository in the contributing section.

I also added the feature idea #30, which is an idea to try to actually list them on the site via the github API. But that's not crucial, just kind of fun 😉

[cdeil]

You're not mentioning astropy-api in #29.
Is that because it should not be used any more now that we have APEs?
If you plan to keep astropy-api for the coming years maybe you can add a sentence about them and link there in #29?

[eteq]

@cdeil - re: astropy-api: in my head, it's mostly replaced by APEs, but it's now mainly a place to store APIs code associated with APEs so that we can keep the APE repo clean. But that's not been firmly decided: @astrofrog, do you have any opinions here?