posit-dev / posit-dev/great-docs

feat: unified Python + R documentation sites (multi-language adapter)

Open
#330 1 comment 1 reaction 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
262
Forks
18
Avg merge
1d 4h
Merged PRs (30d)
14

Description

We'd like to add support for unified documentation sites for projects using multiple programming languages (starting with the Python + R combination) so packages like shinychat and querychat can migrate their sites.

In both cases, the sites have custom landing pages that ask a user which sub-site (Python or R) to navigate to. We could make it so that there's a single Great Docs site that unifies both (one navbar, search index, and theme). Internally we have this spec'd out and this involves:

  • a new sections: config key
  • an R adapter that parses roxygen2 output to produce the same intermediate representation as the Python pipeline
  • a section selector widget in the navbar for switching between languages

Both posit-dev/shinychat and posit-dev/querychat are monorepos with pkg-py/ and pkg-r/ subdirectories and are nice test cases for this work. We need to: (1) start with an internal IR refactor, (2) prototype a working Python + R site for shinychat or querychat from local paths, and (3) add cross-repo git source resolution (this is for getting one docs site built from sources in multiple repos).

cc: @gadenbuie

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the internal intermediate-representation refactor and review the sections: configuration requirement. Prototype a unified site from local pkg-py/ and pkg-r/ paths using posit-dev/shinychat or posit-dev/querychat, then investigate cross-repo git source resolution. Done means a working Python + R site with shared navigation, search, theme, and a language selector.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, python, r
Domain
documentation, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.