Makes .mdformat.toml take precedence

[kdeldycke]

This PR closes #17

Additionally, fixes some docstring rST formatting.

[kdeldycke]

Also, forgot to mentionned, but this PR fixes an issue with mdformat 1.0.0.

The patched read_toml_opts() from previously released mdformat-pyproject 0.7.x can return inconsistent (pyproject_opts, pyproject_path) pair, triggering this traceback:

Traceback (most recent call last):
  File "/home/runner/.local/bin/mdformat", line 10, in <module>
    sys.exit(run())
             ^^^^^
  File "/home/runner/.local/share/uv/tools/mdformat/lib/python3.12/site-packages/mdformat/__main__.py", line 8, in run
    exit_code = mdformat._cli.run(sys.argv[1:])
                ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/runner/.local/share/uv/tools/mdformat/lib/python3.12/site-packages/mdformat/_cli.py", line 56, in run
    opts = {**DEFAULT_OPTS, **toml_opts, **cli_core_opts}
           ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
TypeError: 'NoneType' object is not a mapping

See my CI for more details: https://github.com/kdeldycke/workflows/actions/runs/18754525944/job/53502912176#step:7:20

[csala]

I added some comments. I believe that the current approach may lead to silent conflicts that may be confusing to the user (user edits options in pyproject.toml but observes no behavior changes because a .mdformat.toml exists that they did not spot at first)

[codecov-commenter]

⚠️ Please install the to ensure uploads and comments are reliably processed by Codecov.

Codecov Report

❌ Patch coverage is 96.29630% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 91.48%. Comparing base (35ebee6) to head (1750b85).
⚠️ Report is 3 commits behind head on master.

Files with missing lines	Patch %	Lines
mdformat_pyproject/plugin.py	96.29%	1 Missing ⚠️
❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##           master      #20      +/-   ##
==========================================
- Coverage   92.50%   91.48%   -1.02%     
==========================================
  Files           2        2              
  Lines          40       47       +7     
==========================================
+ Hits           37       43       +6     
- Misses          3        4       +1     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[kdeldycke]

I addressed all the issues but there are conflicting reports of the pre-commits hooks because of tests/pre-commit-test.md. Do you have a preferred way of fixing this?

[kdeldycke]

I addressed all the issues but there are conflicting reports of the pre-commits hooks because of tests/pre-commit-test.md. Do you have a preferred way of fixing this?

OK I decided to aligns the configuration files to prevent any mismatch.

[csala]

@kdeldycke Thank you very much!

There is one last thing: the tests now are a bit redundant, because test_search_config_directory_inside_project is almost the same as test_patched_read_toml_opts_with_pyproject, and same with the without equivalents.

On the other hand, because .mformat.toml exists, now there is no test in which the options are actually loaded from the pyproject.toml file.

To make it right, I would remove the test_search_config_** tests and keep only the test_patched_read_toml_opts** versions, but with all these scenarios (possibly using a tempdir to set things up):

• Only .mdformat.toml → Options from .mdformat.toml are returned
• Only pyproject.toml with options → No options are returned
• Only pyproject.toml without options → No options are returned
• Both .mformat.toml and pyproject.toml, but pyproject.toml has no options → Options from .mdformat.toml are returned
• Both .mformat.toml and pyproject.toml exist and with different options → There is a warning (mock.patch the print_paragraphs function to certify it) and the options from .mdformat.toml are returned.

I'm happy to make these changes myself, either on top of the same PR or after merging it, if you want, or you can give it a go. Your call.

In any case, I'll make the release with the rest to unblock the compatibility problem, and we can re-release afterwards with this one.

[kdeldycke]

I can make the test changes, but not today. 😅 So if you are in a hurry do not hesitate to add them on top of this PR!

[csala]

I can make the test changes, but not today. 😅 So if you are in a hurry do not hesitate to add them on top of this PR!

Alright, I'll do the changes myself and release a new version with this possibly today.

[kdeldycke]

Thanks @csala for the additional tests and merge!

[csala]

Thanks @csala for the additional tests and merge!

Thank YOU for moving this in the first place! Good collaboration altogether.