Repository navigation
Documentation for Extensions: Order and Reference #729
Description
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!
Activity
waylan commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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:
This issue would then become something you could point people to at meetups and conferences.
How's that sound?
facelessuser commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
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 commentedon Oct 9, 2018
Some clarifications:
setup.pysetinstall_requires=["Markdown>=2.5,<2.7"],pipwas 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.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 commentedon Oct 9, 2018
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.
merriam commentedon Apr 14, 2020
Not sure if helps, but I updated much of the extensions tutorial. It includes at least a hint on where to find the priority numbers and how to use them.
There was a bunch of functionality lost with the deprecations. Things happen.
Move Patterns sections. Fix Python-Markdown#729
Refactor Extension API docs (Python-Markdown#946)