feat: order changelog tabs based on importance

[moe-ad]

Closes #705.

Context

As I began working on this, some connected problems were identified and I think it makes sense to outline those first.

Problem one

• Due to the use of toml formatting tools (usually https://github.com/tox-dev/pyproject-fmt pre-commit hook from my observation), there is now a style difference in the array of tables representing towncrier fragment types among projects. Examples:

PyMAPDL (default doc-changelog style, an array of tables)	PyAnsys Geometry (new style due toml formatting, an array of inline tables)

• doc-changelog action's current implementation only adds new types according to the first style. This means the addition of a new default fragment type (like "breaking") to the default configuration would result in modifications with style inconsistencies for projects like pyansys-geometry that have diverged from the default style. In summary:

This would happen	Instead of this

Problem two

• In order to solve Order the changelog tabs based on importance #705, the towncrier configuration for projects needs to be updated automatically such that the type tables are sorted in the right order. Keep in mind that this is an in-place edit.
• Current doc-changelog action file edits are via direct file writes. While this has been sufficient before now (since we were only doing append operations), editing files in-place makes this approach infeasible. This means we need to do file writes much more programmatically.

Problem three

• The natural solution to problem three is to simply use tomli_w for the file writing operations (since we already use its counterpart tomli for parsing).
• Unfortunately, I identified the following limitations of tomli_w:
  • Since tomli does not preserve style information after parsing, tomli_w output will have a style that is different from the original configuration file. This means limiting edits to the towncrier section is not possible (which is what the doc-changelog action should do when it needs to edit files).
  • tomli also doesn't preserve comments upon parsing, meaning the output of tomli_w would have discarded all comment information that was initially present in the configuration file. See the image that follows to better understand the problem.

Proposed solution

• So what is the way forward? The good thing is that I discovered that tomlkit exists and it:
  • Can handle both parsing and writing, so we don't have to depend on two different packages.
  • Preserves way more information upon parsing, including style and comments.
• This pull-request solves Order the changelog tabs based on importance #705 using tomlkit.

Caveats

• We still needed to sort fragment types based on importance, there are some issues with sorting tomlkit container types in-place (by design, see Sorting an Array doesn't persist python-poetry/tomlkit#233 for example) due to the need to preserve style. So during the sort, I essentially needed to construct this container types from scratch (see the initial implementation of sort_towncrier_types in this diff).
• What this meant was that although changes would have been localized to the towncrier section, some style information is now lost. These are best demonstrated via examples:

PyMAPDL style	PyAnsys Geometry style

• And this issue is solved via c2880fd. Open to feedback regarding this if anyone thinks there is a less hacky approach.

Final tests

• These are links to tests that I have created to confirm the end result:
  • https://github.com/ansys/pyansys-geometry/pull/2636/changes
  • https://github.com/ansys/pymapdl/pull/4486/changes
  • https://github.com/ansys/pyfluent/pull/4988/changes (this one even has a bandit section after the towncrier section, which is a good edge case to test against)

[SMoraisAnsys]

Very great job @moe-ad Thanks for handling all those problems at once.

Regarding your comment "What this meant was that although changes would have been localized to the towncrier section, some style information is now lost. These are best demonstrated via examples:" I'm not sure to follow you. Do you mean that using your approach will lead to the pyproject.toml file always being rewritten or only for cases where the section content is missing ?

While the TOML content should be updated in a PR and therefore users could always add back the removed comments, I think moving to tomlkit makes sense. Also, the work around the tiny drawback related to the sort/reverse operation is not that hard to understand. Adding a reference to the problem might be wise for future maintenance though :)

I left some minor comments.

[moe-ad]

Very great job @moe-ad Thanks for handling all those problems at once.

Regarding your comment "What this meant was that although changes would have been localized to the towncrier section, some style information is now lost. These are best demonstrated via examples:" I'm not sure to follow you. Do you mean that using your approach will lead to the pyproject.toml file always being rewritten or only for cases where the section content is missing ?

While the TOML content should be updated in a PR and therefore users could always add back the removed comments, I think moving to tomlkit makes sense. Also, the work around the tiny drawback related to the sort/reverse operation is not that hard to understand. Adding a reference to the problem might be wise for future maintenance though :)

I left some minor comments.

Thanks for the review @SMoraisAnsys.

What I meant by my statement is that without the hack in c2880fd, there would have been slight differences between the style of what doc-changelog would have comitted and the initial style.

In summary, the implementation in this PR retains the style in the original pyproject.toml, even the comments. See the file changes in the test cases.

[SMoraisAnsys]

Thanks @moe-ad I'll let other give their opinion but it seems fine to me. Great job !

[RobPasMue]

I'm fine with these changes - thanks @moe-ad for carrying it out!