{"id":17652017,"url":"https://github.com/edgararuiz/pkgsite","last_synced_at":"2025-04-13T02:23:23.624Z","repository":{"id":258838208,"uuid":"871222146","full_name":"edgararuiz/pkgsite","owner":"edgararuiz","description":null,"archived":false,"fork":false,"pushed_at":"2024-12-02T14:17:28.000Z","size":687,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-10T06:06:33.694Z","etag":null,"topics":["quarto","r","website"],"latest_commit_sha":null,"homepage":"https://edgararuiz.github.io/pkgsite/","language":"R","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edgararuiz.png","metadata":{"files":{"readme":"README.Rmd","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-11T14:07:03.000Z","updated_at":"2024-12-02T14:16:59.000Z","dependencies_parsed_at":"2024-12-11T08:52:16.192Z","dependency_job_id":null,"html_url":"https://github.com/edgararuiz/pkgsite","commit_stats":null,"previous_names":["edgararuiz/pkgsite"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgararuiz%2Fpkgsite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgararuiz%2Fpkgsite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgararuiz%2Fpkgsite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edgararuiz%2Fpkgsite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edgararuiz","download_url":"https://codeload.github.com/edgararuiz/pkgsite/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248655012,"owners_count":21140408,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["quarto","r","website"],"created_at":"2024-10-23T11:44:25.777Z","updated_at":"2025-04-13T02:23:23.581Z","avatar_url":"https://github.com/edgararuiz.png","language":"R","funding_links":[],"categories":[],"sub_categories":[],"readme":"---\noutput: github_document\n---\n\n\u003c!-- README.md is generated from README.Rmd. Please edit that file --\u003e\n\n```{r, include = FALSE}\nknitr::opts_chunk$set(\n  collapse = TRUE,\n  comment = \"#\u003e\",\n  fig.path = \"man/figures/README-\",\n  out.width = \"100%\"\n)\n```\n\n# pkgsite\n\n\u003c!-- badges: start --\u003e\n[![R-CMD-check](https://github.com/edgararuiz/pkgsite/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/edgararuiz/pkgsite/actions/workflows/R-CMD-check.yaml)\n[![Codecov test coverage](https://codecov.io/gh/edgararuiz/pkgsite/branch/main/graph/badge.svg)](https://app.codecov.io/gh/edgararuiz/pkgsite?branch=main)\n\u003c!-- badges: end --\u003e\n\n## Intro\n\nThe goal of `pkgsite` is to make it easier to create a package website using\nQuarto. It attempts to do for R what \n[Quartodoc](https://machow.github.io/quartodoc/get-started/overview.html) does \nfor Python package documentation. \n\n## When should I use `pkgsite`?\n\nIn the vast majority of cases [`pkgdown`](https://pkgdown.r-lib.org/index.html)\nis enough to create top tier package website. `pkgdown` is a well developed\nmature package that covers all sorts of special needs. In fact, `pkgsite` \nuses `pkgdown` to perform several operations.\n\nSo apart of simply wanting a Quarto site for your R package, a couple of reasons \nto use `pkgsite` are:\n\n- **You want to use the output \n[\"freeze\"](https://quarto.org/docs/projects/code-execution.html#freeze) \ncapabilities in Quarto** - You would like  the examples in the help pages to\nrun, but, the ability to run such examples depend on specific technologies\nto be accessible to where the site is being \npublished, which is usually GitHub. Examples of those technologies could be\ndatabases, Spark and Large Language Models. The idea would be to render the\nwebsite locally, where you would have access to the needed technologies, and\nmake commit the resulting \"_freeze\" folder to the repository. This will allow\nany re-building of your website by GitHub to have the necessary code output to\ncreate the HTML files.\n\n- **You want to build a unified site** - Your packages from your project may be\navailable in multiple languages, and wish to make a unified website. The idea\nhere is if you have output from Quartodoc from the Python side of your project,\nthat needs to be available in the website along with the references from the\nR side of your project. \n\nAn example of having both reasons to use `pkgsite`, is the \n[`mall`](https://github.com/mlverse/mall) package. This project has a Python, and\nan R package. And the examples in both packages need an LLM in order to work, \nhere is the resulting [reference pages](https://mlverse.github.io/mall/reference/).\n\n## Installation\n\nYou can install the development version of pkgsite from [GitHub](https://github.com/) with:\n\n``` r\n# install.packages(\"devtools\")\ndevtools::install_github(\"edgararuiz/pkgsite\")\n```\n\n## Usage\n\nIn it's current state, `pkgsite`'s functions build on top of each other, in \norder to create the reference pages and the index page. The top tier function\nis `write_reference()`. \n\n```{r}\nlibrary(pkgsite)\n\nwrite_reference()\n```\n\n\nThe function uses sensible defaults, so even by calling it without changing any \narguments should work without errors. Internally, the function applies such\nsensible values if specific arguments are left `NULL`.\n\n## Configure via the '_quarto.yml' file\n\nJust as with [quartodoc](https://machow.github.io/quartodoc/get-started/overview.html#basic-use),\n`pkgsite` also supports configuration via the '_quarto.yml' file. You just need\nto add a 'pkgsite' section at the top level of the yaml file. Here is an example\nof the values that are available for use:\n\n```yaml\npkgsite: \n    dir: \".\" # location of the package\n    reference:\n      dir: reference # target folder for qmd files\n      template: inst/templates/_reference.qmd # reference template location\n      not_run_examples: true # Flag to run the 'Not Run' examples\n      index:\n        file: index.qmd # name of the index file to use\n        template: inst/templates/_index.qmd # template for index qmd file\n```\n\nVia the YAML file, it is also possible to create custom grouping sections for\nyour functions in the index file. Here is an example of how to accomplish what\nis setup for this package's website:\n\n```yaml\npkgsite: \n    dir: \".\"\n    reference:\n      dir: reference\n      template: inst/templates/_reference.qmd\n      not_run_examples: true\n      index:\n        file: index.qmd\n        template: inst/templates/_index.qmd\n        contents: # add 'sections' levels\n          - section: Quarto file creation\n            contents: \n            - write_reference.qmd\n            - write_reference_index.qmd\n            - write_reference_pages.qmd\n          - section: Conversion functions\n            contents:\n            - index_to_qmd.qmd\n            - rd_to_qmd.qmd\n            - rd_to_list.qmd\n```\n\nThe `mall` package has another example of how to configure the YAML file: \n[mall/_quarto.yml](https://github.com/mlverse/mall/blob/main/_quarto.yml#L67-L90)\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgararuiz%2Fpkgsite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedgararuiz%2Fpkgsite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedgararuiz%2Fpkgsite/lists"}