Closed vincentarelbundock closed 4 months ago
@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.
In case you want to see it "live", I updated one of my websites: https://marginaleffects.com/vignettes/predictions.html
This PR adds an
autolink
argument torender_docs()
to process vignettes, man pages, and home page usingdownlit
. 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 apkgdown.yml
file in the root of the website like this:Users should probably host this file in
altdoc
Warning:
downlit
will only recognize internal links ifpkgdown.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:
altdoc/pkgdown.yml
automatically withsetup_docs()
pkgdown.yml
hosted on a live website.