Documentation issues - Quickstart gives errors, and tutorial use of .ext fails

[robintw]

I've been trying to get familiar with PySTAC recently, and have found a number of issues with the documentation.

Quickstart
Running the code in the quickstart guide at https://pystac.readthedocs.io/en/1.0/quickstart.html gives a number of errors. For example, the first code block runs from pystac import STAC_IO, which fails as it should be from pystac import StacIO. A bit further down, the call to cat.get_children() fails with a TypeError: list indices must be integers or slices, not str (I couldn't work out how to fix this). I suspect there may be other issues too.

Tutorials
In the Creating a Landsat STAC tutorial (https://pystac.readthedocs.io/en/1.0/tutorials/creating-a-landsat-stac.html#Adding-the-EO-extension), it tells you to run item.ext.enable('eo') but this fails, saying that the ext attribute doesn't exist. After asking this question on the STAC Gitter chat, I was told to follow the instructions here, which worked.

(As an aside, I'd be interested as to why the .ext accessor was removed, as it seems to be a nicer way of adding extensions)

[duckontheweb]

Thanks for raising this @robintw. The out-of-date documentation and tutorials are a known issue from #606, #462, #602, and #384. I plan on addressing these in the next release, so stay tuned and sorry for the long delay in updating these.

[duckontheweb]

(As an aside, I'd be interested as to why the .ext accessor was removed, as it seems to be a nicer way of adding extensions)

@robintw I think this was removed when STAC made the change from short extension IDs (e.g. eo) to full schema URIs. Those short IDs gave us a nice argument to the .ext method, but I'm not sure what we could use instead. Any thoughts?

[robintw]

Hmm, that's interesting. I wish STAC hadn't removed short extension IDs, they sound useful!

I'll have a think about this and get back to you.

[duckontheweb]

One possibility that I considered here was to use the prefix (e.g. eo for the Electro-Optical Extension), but not all extensions have a prefix (Version Extension is one example), so we couldn't rely on that consistently.

One option would be to just define our own convention. We could use a lower-cased version of the extension name with spaces and - characters replaced by underscores. Electro-Optical would be electro_optical, Scientific Citation would be scientific_citation, etc. That seems like it could be intuitive enough to be useful.