disincentivize usage of functions that expose toml::Table in Config

[JulianGmp]

hi there,

firstly, thank you for your continued work on mdbook, it's a great tool :)

This is related to #2037, which I encountered while trying to deserialize the exposed Map/Table into a user defined struct in a preprocessor I'm writing.

Using get_deserialized_opt seems much more preferable to get_preprocessor (and get_renderer for that matter). However, I merely happend to stumble across that function while looking through config.rs.
I don't think I'm alone with this, I did a brief search over the preprocessors listed in the third party plugins page and the ones that do have options use get_preprocessor.

The one caveat for get_deserialized_opt is that you have to pass "preprocessor.my_thing" instead of "my_thing", so I made get_renderer_deserialized and get_preprocessor_deserialized for convenience. I added that to the example to incentivize people writing new preprocessors to use it.

I also marked get_renderer and get_preprocessor as deprecated. However this might be bold. There are probably valid use cases for these functions, unless mdbook were to remove the exposed toml type(s) like #2037 describes (which would significantly change mdbook::config::Config's interface).

Note that this also results in 3 deprecation warnings in the tests.
I haven't addresses these, because I think the decision whether to deprecate them at all should be done by the maintainers, I'm just a user of the library/tool.

[danieleades]

i think deprecating the methods that expose the toml type and pointing users towards get_deserialized_opt is the right way to go

[rustbot]

:umbrella: The latest upstream changes (possibly #2681) made this pull request unmergeable. Please resolve the merge conflicts.

[JulianGmp]

I went ahead and rebased this branch from the current master, since the test structure was changed. I still think this would be a good inclusion. Whether or not the old functions should be deprecated I still want to leave to the maintainers. Especially the changes in src/book/mod.rs aren't great imo, since they add an unnecessary copy. While I don't think this is a use case for people writing their own renderers or preprocessors, it still is a minor performance regression. I could imagine adding some specific functions to get a specific config value like "preprocessor.some_value" by reference.

In any case, I want to kindly ask for a review, since this has gone a bit stale.

[ehuss]

I'm going to close as Table is no longer publicly exposed (largely through https://github.com/rust-lang/mdBook/pull/2773). Thanks for the PR, though!

[JulianGmp]

I'm going to close as Table is no longer publicly exposed (largely through #2773). Thanks for the PR, though!

Ah, it achieves the same goal, thank you for working on this! :) I'll update my preprocessors and renderer once the next release comes around.