Documentation for Extensions: Order and Reference

[jambonrose]

Hi,

Excited to discover the release of v3 last week! Thanks for all the hard work.

I'm reviewing the documentation so that I may update the superscript and subscript extensions that I maintain. I'd like to suggest a few changes, and I'm open to helping on this front with PRs.

The documentation currently lays out the old way of creating an extension, and then discusses the new way. While this makes sense for historical purposes, this is likely the opposite order a new-comer would expect. Would you be open to starting with the recommended/modern way of creating an extension, and then adding notes about the previous method?

The documentation provides a partial list of "Generic Pattern Classes," including a few legacy processors. Would you be open to providing a full list of the pattern classes, and linking to extensions that demonstrate their use? For existing extension maintainers, would you be open to adding notes about which modern pattern classes should replace the legacy versions?

Thanks again!

[waylan]

Those all sound like good ideas to me. Personally, I haven't had much time to spend on it so any help is appreciated.

Note that there is also a tutorial on the wiki which has not been updated at all. I'd like to see that incorporated into the documentation itself. I'm wondering if the Extension API documentation should be broken up into multiple pages.

[facelessuser]

I like these ideas as well. Putting new conventions first makes sense. We shouldn't lead with legacy. And better extension example is always helpful.

[jambonrose]

OK! I've got some cleanup I'm finishing up on my two repos, but after that I'll then take a stab at the tutorial and extension docs. I'm very much in favor of splitting up the documentation, as it's currently an overwhelming amount of information.

Quick question: is there a deprecation timeline for the legacy tools like SimpleTextPattern?

[waylan]

Quick question: is there a deprecation timeline for the legacy tools like SimpleTextPattern?

That's a good question. We havn't discussed any specific timeline. I expect the answer to be: when a significant number of third party extensions have adopted the new stuff.

[jambonrose]

Hmmm.

With your permission, I'd like to create a new issue for new developers. The goal would be to get new developers to either:

• open new issues on the extensions that haven't migrated their extensions to the new API (I was not aware of the v3 release until someone opened an issue!)
• open PRs on those extensions to migrate the extension (once a new issue has been filed)

This issue would then become something you could point people to at meetups and conferences.

How's that sound?

[facelessuser]

I was not aware of the v3 release until someone opened an issue!

That's how I find all breaking API changes when using Python modules 😏 .Either my unit tests break when I push something new, or someone creates an issue.

[waylan]

See How do I get notified when a new version of a project is released? for how the Python community in general deals with this. Unfortunately there is no standardized way to get notified and I'm not interested in creating some one-off system for Python-Markdown.

[waylan]

Btw, GitHub provides a feed of releases at https://github.com/Python-Markdown/markdown/releases.atom. You can always follow that feed to be notified of new releases. And of course, the releases notes for new releases are always published in the docs.

[facelessuser]

I think the best way if you are afraid of getting caught unaware, is to lock your self to specific major versions in your setup file. Minor and bug fix releases shouldn't usually break your module, but major releases are always usually free to break things, sometimes without deprecation paths.

[facelessuser]

I think you run cron jobs on things like Travis and other CI services. I haven't yet taken advantage of this myself, but one day I'd like to play with something like a weekly test run.

[jambonrose]

Some clarifications:

• the fact that I was not aware of the release was not meant as a criticism, and I am not suggesting we try and find a way to notify people systematically of releases (either here or in the Python ecosystem generally)
• my packages use code that is legacy, but still supported. However, as my setup.py set install_requires=["Markdown>=2.5,<2.7"], pip was raising a warning, which caused a user to open an issue (which I am grateful for). Currently, I have not upgraded to the new Extension API, which people may be unaware of.
• IMHO, unless people are made aware of the new API, then developers won't update their code. If your goal is to wait until these packages switch over before deprecating the legacy API, then there's a chicken and egg problem.
• rather than have you do the legwork of telling people, I was suggesting providing an issue to act as a central notification log to allow others to help you. The third-party extension list in the wiki would serve as the list of projects that must be notified/updated, and the new issue would provide check-boxes so that other people could inform you/others as to whether the maintainer has been notified and whether the code has been updated (with PRs encouraged)

While this offloads/distributes a lot of work, it will also result in some community work and messaging. I'm not sure where you are in the development lifecycle, and therefore didn't want to surprise you with an issue of this sort.

For the moment, I'll have a go at the documentation, and save this idea for later.

[facelessuser]

I personally don't see a problem with the community creating a wiki page detailing extensions that are not currently compliant with the 3.0 new methodologies. The community could update it as new non-compliant packages are discovered, or cross them off once they become compliant. As the wiki is open to the community, I don't see a problem with that.

I also don't see a problem with creating an issue called something like "Remove legacy code" (or something like that). It is indeed a task that needs to be done. There we could just link the wiki page. If it works well, we have feedback of 3.0 adoption, if not, I don't see how it would cost us anything to have.

That's just my opinion.