Split API changes into individual pages #11637
Conversation
doc/api/api_changes_old.rst
Outdated
|
|
||
| .. toctree:: | ||
| :glob: | ||
| :maxdepth: 1 |
There was a problem hiding this comment.
The most recent changes should be at the top. Add :reversed:
| Changes for 0.40 | ||
| ================ | ||
|
|
||
| :: |
There was a problem hiding this comment.
Since we have automatic highlighting, this will be highlighted as python. Use .. code-block:: text if converting to ReST is too much effort.
| .. toctree:: | ||
| :maxdepth: 1 | ||
|
|
||
| api_changes_old |
There was a problem hiding this comment.
This is a bit confusing: We state that we list the API changes for the most recent version and the first entry is "Old changes" without a further comment.
Also we have two toctrees that have a different purpose. They amost visually merge (only some additional space in between, which I originally assumed was just a layout bug.
| @@ -19,8 +26,8 @@ For new features that were added to Matplotlib, please see | |||
|
|
|||
| next_api_changes/* | |||
There was a problem hiding this comment.
The scope and logic behind this is unclear to me:
- Why are some things in extra files, while others are listed in the text below.
- This mixes different levels. Deprecations is clearly on a higher level than matplotlib.Axes.get_tightbbox now includes all artists. They should not occur side-by side.
There was a problem hiding this comment.
The problem is that before doing a release everything is in the next_api_changes, but when doing a release everything gets merged into one file to make sure it's consistent with titles etc., and this bit is commented out (see above comment in the code). At the moment we're between these two so have a mix of them turning up. This will be fixed before release.
There was a problem hiding this comment.
Couldn't we just write all the API changes in a single file? I think this was proposed in another thread. Might be a problem though with getting many merge conflicts.
Alternatively, collect the unmerged stuff on a separate page. Or at least Give the list of unmerged stuff a section title and comment or a .. note:: block. The current state is a bit confusing for other developers not familiar with the process (e.g. me) and for people accidentially ending in devdocs.
There was a problem hiding this comment.
Yes, the problem is too many conflicts if there is one file. @tacaswell has a script that merges them all up....
There was a problem hiding this comment.
I've added a note to hopefully explain things a bit better.
There was a problem hiding this comment.
Good enough for now.
The full text list below should be moved into its own file in 'prev_api_changes'
All the files in 'next_api_changes' should be moved to the bottom of this page
This note, and the toctree below should be commented out
This seems cumbersome to me. I understand that the we originally need multiple files to prevent merge conflicts. As far as I have understood this list and following stuff is generated from these files a bit prior to a release. Why not create all of this in a separate file directly?
But that can be part of another PR.
|
👍 with two approvals I'm going to merge |
This gets rid of the huge API changes page, and splits it into individual files for each release.