What would be the appropriate way to set up a quartodoc to document multiple projects?

[zykezero]

basically the title. Saw the presentation on this at posit and got real excited for it.
My org is large with lots of internal products and teams. We are really digging into documentation and I want to show off the capabilities of quartodoc.

One requirement I can see being asked is how easy it would be to add new projects. So far I have been unable to do this.

I was hoping it was something like this;

quartodoc:
    sections:
        - package: pkg1
          dir: project_docs/pkg1
          title: ... etc
        - package: pkg2
          dir: project_docs/pkg2
          title: ... etc

But there is a requirement for a package to be named at the root so obviously not gonna cut it.

Thanks in advance.

[machow]

Hey! You should be able to set the top-level package to null, and document packages by using the full path to each function (or set package: for each section).

For example, here is a config that documents pins and quartodoc:

project:
  type: website

# tell quarto to read the generated sidebar
metadata-files:
  - _sidebar.yml


quartodoc:
  package: null

  # write sidebar data to this file
  sidebar: _sidebar.yml

  sections:

  # pins specific documentation ----
  - title: pins
    package: pins
    contents:
      - board_connect
      - board_s3

  # quartodoc specific documentation ----
  - title: quartodoc
    package: quartodoc
    contents:
      - get_object
      - MdRenderer

  # or don't specify package, and use full name ----
  - title: mixed
    contents:
      - quartodoc.collect
      - pins.board_gcs
 

Does something like that work for you?

[zykezero]

Hey thanks so much for answering.

It doesn't look like I will be able to set sub-directories per package right? I'm doing my best to iron out any potential resistance that I can. One of those things is that I know that our teams will want to just point to the subdirectory where all the qmds are instead of listing out each qmd in the navigation yml. How would you suggest I go about making this happen?

Small-ish follow up; I see that we can pull in everything within a module without listing everything out, fantastic. Does this extend to naming package / subpackage to auto collect? I'm at a pretty big company, tons of work never documented, I am pushing for quarto+quartodoc and others are pushing for mkdocs. A big reason why people want to use mkdocs is because they just want to point to the directory / package and let the process just pick up everything inside.

For instance, in this food based example;

• fruits
  • __init__.py
  • planting.py
  • banana
    • __init__.py
    • peel.py
    • bunch.py
  • apple (...etc)

The desired process is to just point to package: fruits, and it would bluntly nest everything within it.

Fruits as the top level fold, planting.py as a page under Fruits, banana as a second level fold, peel and bunch as pages, and the contents of planting, peel, bunch are all just bluntly embedded.

If you could fill me in on this, if it's doable (if it's doable with some extra work on my end)
If it's on a road map, if it is - how far along? ya know, I want to make a strong case for quartodoc and this is the only place where I see mkdoc as having an advantage.

Thanks again, I went all in on this after seeing it previewed at positconf.

[zykezero]

Also, I just tried this out, while quartodoc build processes just fine, quarto preview fails due to duplicated mapping key. So close.

quartodoc:
  package: pins
  sidebar: reference/_sidebar.yml
  dir: reference/pins_example
  sections:
    - title: pins.boards
      package: pins.boards
      contents:
        - name: BaseBoard
          children: embedded
    
quartodoc:
  package: quartodoc
  sidebar: reference/_sidebar.yml
  dir: reference/quarto_example
  sections:
    - title: quartodoc.ast
      package: quartodoc
      contents:
        - name: ast
          children: embedded

[machow]

Do they have to be many docs generated as part of the same quarto website? What about generating each package doc individually?

This seems similar to how something like pkgdown would do it:

project:
  type: website

# tell quarto to read the generated sidebar
metadata-files:
  - _sidebar.yml

quartodoc:
  package: pins
  sidebar: reference/_sidebar.yml
  dir: reference/pins_example
  sections:
    - title: pins.boards
      package: pins.boards
      contents:
        - name: BaseBoard
          children: embedded

project:
  type: website

# tell quarto to read the generated sidebar
metadata-files:
  - _sidebar.yml

quartodoc:
  package: quartodoc
  sidebar: reference/_sidebar.yml
  dir: reference/quarto_example
  sections:
    - title: quartodoc.ast
      package: quartodoc
      contents:
        - name: ast
          children: embedded

It also has the advantage of worrying about each API individually during build, rather than needing to worry about all of them at the same time.

The desired process is to just point to package: fruits, and it would bluntly nest everything within it.

I think it will unfortunately be a while until this is in quartodoc. I'm aiming right now at more user-facing-style API docs (similar to pkgdown), so rather than documenting everything in a nested way, am focused on document the user-relevant pieces as flat as possible!

That said, it should let you document specified modules / sub-modules. (afaik doing what you mention with mkdocs would also take some scripting, but I could be wrong?).

[zykezero]

I'm sure it would, but I can't confirm.

I haven't had a chance to do it yet but I was going to try and do project folders with individual quartodoc yamls. Just gotta find a thing that works for us.

I'm still new to package documentation packages, I've only started digging into it for this company project, still fairly new. Thank you for being so patient and helpful. Last question, I know roxygen is used for documenting R scripts, but I'm not clear on how to get these .Rd files to qmd.
Okay, so other options include kintr::spin, and pkgdown. hmmmmmmmmmm

Okay last thing promise, any ideas on how to process .sql files to a format that I can render? haha :|