Is your change request related to a problem? Please describe.

Cached parsed docstrings are causing more issues than they solve. See mkdocstrings/python#183. Cache invalidation of course! The second of the two hardest problems in computer science, after naming things and before off-by-1 errors.

Templates can very easily iterate on the sections once. Other programmatic uses can store the sections in a variable. No need to cache it. I think I initially decided to cache it because it would allow extensions to easily modify sections, which are data structures, instead of having to mess with the raw docstring. But we can solve this too, see next section.

Describe the solution you'd like

Instead of caching the parsed docstrings, provide utilities to make it as easy to modify raw docstrings. Typically:

• appending a section: docstring.append(DocstringSectionStuff(...)). Here, we don't care what style is used: append will internally parse the docstring using the attached style (or auto-infer it when the feature is available), append the section, and re-dump everything.
• that means we must implement the opposite of parsers: writers?
• that will incur a small performance cost too, since we'll more often parse docstrings, but I don't expect them to be parsed a lot anyway (not a lot of extensions modify docstrings, and these extensions do not modify a lot of docstrings).
• append is just a suggestion, we should design a good API. For example, and related to perfs, we should allow appending several sections at once, etc. Context manager (transactions)?

Describe alternatives you've considered

Not considering. Needs to be done.

Additional context

This will need a deprecation period of course, with warnings and all. We should also reach out to extension authors using cached parsed sections. We use this ourselves in griffe-warnings-deprecated I believe.