render_docs(autolink = TRUE) uses downlit

[vincentarelbundock]

This PR adds an autolink argument to render_docs() to process vignettes, man pages, and home page using downlit. This will auto-link function calls to web-based documentation.

Links to external functions work without further intervention. Links to an altdoc website requires users to add a pkgdown.yml file in the root of the website like this:

urls:
  reference: https://vincentarelbundock.github.io/tinytable/man
  article: https://vincentarelbundock.github.io/tinytable/vignettes

Users should probably host this file in altdoc

Warning: downlit will only recognize internal links if pkgdown.yml is already hosted live on the website. This means that this won't work the first time the website is generated, and that local updates will not be reflected in links.

TODO:

• Create altdoc/pkgdown.yml automatically with setup_docs()
• Check docute
• Check docsifiy
• Check mkdocs
• How do we do unit tests for this? The tricky part is it requires a pkgdown.yml hosted on a live website.

[vincentarelbundock]

@etiennebacher I think this is ready for review now.

In the end, I decided to set autolink=FALSE by default for reasons explained in this part of the new documentation:

Auto-link:

 When the ‘autolink’ argument is ‘TRUE’, ‘altdoc’ will use the
 ‘downlit’ package to replace the function names on the package
 website by links to web-based package documentation. This works
 for base R libraries and any package published on CRAN.

 To allow internal links to functions documented by ‘altdoc’, we
 need to include links to correct URLs in the ‘altdoc/pkgdown.yml’
 file. By default, this file is populated with links to the first
 URL in the ‘DESCRIPTION’. When calling
 ‘render_docs(autolink=TRUE)’, the ‘pkgdown.yml’ file is moved to
 the root of the website.

 Importantly, ‘downlit’ requires the ‘pkgdown.yml’ to be live on
 the website to create links. This means that links will generally
 not be updated when making purely local changes. Also, links may
 not be updated the first time an ‘altdoc’ website is published to
 the web.

 Note that the ‘autolink’ argument works best for Quarto-based
 websites. ‘mkdocs’ appears to ignore ‘downlit’ annotations
 altogether. ‘docute’ and ‘docsify’ display ‘downlit’ annotations,
 but CSS styling and code highlighting sometimes suffer.

[vincentarelbundock]

In case you want to see it "live", I updated one of my websites: https://marginaleffects.com/vignettes/predictions.html

[etiennebacher]

Oh yeah that looks great, nice one! Too bad it doesn't work with mkdocs but the example with marginaleffects looks really good.

I have some comments about some code refactor but I'm fine with the functionality. I think it's good to keep it opt-in for now if it messes up the formatting for docsify and docute

[etiennebacher]

Thanks, feel free to merge if you're done