Function calls in vignettes could link to the man page

[vincentarelbundock]

pkgdown does this.

Probably requires some regex magic.

[etiennebacher]

Regex is probably going to be very tricky here. You could try downlit:::downlit_md_path() on the vignettes once they are rendered as md (see https://github.com/etiennebacher/altdoc/issues/27 for small caveats)

[vincentarelbundock]

Actually, I think that if we render the vignettes using Quarto, we get links automatically: https://marginaleffects.com/articles/comparisons.html

[etiennebacher]

Oh that's cool

[vincentarelbundock]

What I wrote above is incorrect: Links are not added automatically in quarto. I opened a PR to resolve this:

https://github.com/etiennebacher/altdoc/pull/273

[zeileis]

The PR was merged but this issue is still open. I think this is because it still does not work everywhere, does it? (At least it does not for me, even with autolink = TRUE.)

Relatedly, it would be good to hyperlink the topics in the "See Also" sections of the manual pages. References to functions in the same package could be hyperlinked within the altdoc site. References to other packages could resolve to rdrr.io (which pkgdown uses as well).

[vincentarelbundock]

So I realized after doing a bunch of work that Quarto can autolink by adding a line to the preamble.

Leaving this open for now because I need to remove the cruft from that merged PR.

Good call on the See Also. I'll look into it when I find time (probably after UseR!)

[vincentarelbundock]

@zeileis I think you might be able to get function links everywhere by adding this to the bottom of your altdoc/quarto_website.yml:

format:
  html:
    code-link: true

Your betareg website looks fantastic, BTW!

[zeileis]

Hmm, the code-link setting does not seem to have an effect on the "See Also" sections. The README is linked but only to rdrr.io and not to the man-pages in the altdoc page itself. The NEWS are also not linked. But maybe I forgot to set something correctly.

And, yes, I like the look of the betareg page, too. But it is altdoc/quarto which makes this easy. I didn't have to do a lot to get something really nice.

[vincentarelbundock]

Thanks. Reopening, and will check later.

[vincentarelbundock]

@zeileis I'm not sure this is going to fix the "See Also" problem, but I think the lack of internal links is likely due to the absence of a pkgdown.yml file in the root directory of your live website. For example:

http://marginaleffects.com/pkgdown.yml

Has this content:

urls:
  reference: https://marginaleffects.com/man
  article: https://marginaleffects.com/vignettes

Note that this YAML file must be live on the internet when downlit is called. So you probably need to upload it to your server, and then rebuild the site.

[zeileis]

Thanks, Vincent, I just told you in person but just to keep Etienne in the loop as well: Putting pkgdown.yml into the root directory improved the situation but did not resolve everything. In some places (e.g., README, manual pages and vignettes) function names are hyperlinked, wenn they are followed by opening round brackets. But without round brackets (e.g., in "See Also") or in some other places (e.g., NEWS) I didn't get it to work yet...

[vincentarelbundock]

The lack of links in NEWS is a problem, but I think the parenthesis requirement for links is a design choice by downlit. Here's what their README says:

[zeileis]

OK, thanks. Not sure what pkgdown then does differently for the "See Also" sections. This also recognizes fun without further formatting.

As for the NEWS, I thought that it might be a .md vs. .qmd issue but the result was the same no matter which suffix I used (unless I overlooked something).