Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add R package docs to quarto page #3

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Conversation

gadenbuie
Copy link

@gadenbuie gadenbuie commented Aug 28, 2024

This PR moves the Python documentation from /reference to /reference/python and adds /reference/r with the R package documentation.

Building the package docs is a bit bespoke:

  1. We use tools::pkg2HTML(), a function new to R in 4.4.1. This function generates a single-page HTML document for a package.

  2. We then do a few back-and-forth transformations with the HTML to commonmark and back, with some mucking around with the HTML via rvest and xml2 to remove unneeded nodes and generally clean things up.

  3. In the end, we create a single page for each function. We then re-use the Python reference listing, but replace "Python" with "R". If the packages diverge, we could easily write reference/r/index.qmd by hand.

I updated the Makefile to track all these bits:

make docs  # make and render the docs

make docs-python  # make just the python docs
make docs-r       # make just the R docs
make docs-preview # makes python+r docs and then previews
quarto preview  # call this to make nothing and just preview

Ideally we'd add redirects for the pages I moved from reference/*.qmd to reference/python/*.qmd, but the package is young and those files are written automatically by quartodoc; I don't think it's worth it.

I did think it was worth adding a page at reference/ (which isn't linked to from anywhere) that gives anyone who lands there two cards to pick between the R and Python references.

Finally, I also renamed quarto/ to docs/. It's a more immediately clear name and I think a better practice for these multilingual monorepos.

@gadenbuie gadenbuie requested a review from jcheng5 August 28, 2024 01:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant