Improve documentation

[mpadge]

@quantsch Thanks so much for this package! I use it in my own r2readthedocs package, and we @ropensci also use it in our own meta-documentation suite.

Through that usage, I had seen your deprecation warnings, and got around to updating things today. Nice work on the great improvements to the package, which definitely make it more robust and flexible. Thanks for that!

That said, the error encountered in #19 meant that I had to figure out what was going wrong, which required me to try to understand the new as_markdown() function. I could find nothing in the documentation to help that function make sense, and the sole recommendation that people read the vignette is useful, but my usages are almost entirely based on file rather than package translations, so that didn't help either. The README jumps straight through to "Extension" before describing how to actually use the main functionality. That left me at a complete loss, and I had to clone the repo and read through the actual code to understand how to use it.

Please consider this issue either as a motivation yourself to improve the documentation both of the main package entry points of README and in https://github.com/quantsch/Rd2md/blob/main/R/Rd2md-package.R, as well as documentation of the main functions. Or, if you're willing, I'd be happy to do you the hopefully helpful favour of casting a pair of external eyes over those bits and drafting an initial PR for you?

Thanks again for the great work in further developing this really useful package!

[quantsch]

Hi @mpadge, great to hear that feedback, much appreciated!

I looked into #19 and opened #21 for further details. Let me look at that in the next few days.

As for this issue regarding documentation improvement, I agree. Given you have already looked at it in detail, which functions would you say do I need to cover in the introduction (on top of as_markdown()). Feel free to draft a PR, would be of great help!