quarto-dev / quarto-cli

Open-source scientific and technical publishing system built on Pandoc.
https://quarto.org
Other
3.7k stars 302 forks source link

Merge sidebar entries using the id field #8449

Open machow opened 7 months ago

machow commented 7 months ago

Bug description

Continuing from discussion w/ @cscheid and crew. Currently, quartodoc outputs a sidebar.yml file, which contains the full quarto configuration for a API Reference sidebar entry.

For example, it might looks like this:

generated _sidebar.yml

website:
  sidebar:
  - contents:
    - api/index.qmd
    - contents:
      - api/get_object.qmd
      - api/preview.qmd
    id: api
  # Note the dummy sidebar below ensures the API Reference sidebar doesn't get
  # put on every page.
  # See https://github.com/machow/quartodoc/issues/170
  - id: dummy-sidebar

_quarto.yml

project:
  type: website

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

# FAILED ATTEMPT TO EXTEND SIDEBAR CONFIG ---------------
website:
  sidebar:
    - id: api
      collapse-level: 1

# /end sidebar config extending --------------------

quartodoc:
  # the name used to import the package you want to create reference docs for
  package: quartodoc

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

  sections:
    - title: Some functions
      desc: Functions to inspect docstrings.
      contents:
        # the functions being documented in the package.
        # you can refer to anything: class methods, modules, etc..
        - get_object
        - preview

Steps to reproduce

Something like this:

_quarto.yml

website:
  sidebar:
    - id: api

_sidebar.yml

website:
  sidebar:
    - id: api
      title: ABCDEFG

Expected behavior

The sidebar gets updated with the title in _sidebar.yml.

(Note that if the expected behavior is not reasonable on the quarto side, that's totally fair! We can work around it / set expectations to quartodoc users!)

Actual behavior

No updates occur (I think the first sidebar with a given id gets used, but am not too sure on the merge dynamics going on here).

Your environment

MacOS

Quarto check output

Quarto 1.4.549
[✓] Checking versions of quarto binary dependencies...
      Pandoc version 3.1.11: OK
      Dart Sass version 1.69.5: OK
      Deno version 1.37.2: OK
[✓] Checking versions of quarto dependencies......OK
[✓] Checking Quarto installation......OK
      Version: 1.4.549
      Path: /Applications/quarto/bin

[✓] Checking tools....................OK
      TinyTeX: (not installed)
      Chromium: (not installed)

[✓] Checking LaTeX....................OK
      Tex:  (not detected)

[✓] Checking basic markdown render....OK

[✓] Checking Python 3 installation....OK
      Version: 3.10.2
      Path: /Users/machow/.virtualenvs/quartodoc/bin/python3
      Jupyter: 5.5.0
      Kernels: python3, venv-siuba, venv-tidyselect, venv-siuba-docs2, venv-pins-python, venv-shout, venv-vetiver-test, venv-siuba-polars, venv-data-analyses, venv-intro-to-siuba, venv-tidyverse-dashboard-duckdb, venv-gt-python, venv-gh_reader, venv-stadium-economics, venv-vetiver-python, venv-shiny-examples, venv-duckops, venv-quartodoc, venv-pyshiny-site, venv-notes, venv-siuba-docs, venv-siuba-workshop, venv-griffe

[✓] Checking Jupyter engine render....OK

R scripting front-end version 4.1.2 (2021-11-01)
[✓] Checking R installation...........(None)

      Unable to locate an installed version of R.
      Install R from https://cloud.r-project.org/
machow commented 7 months ago

cc @gadenbuie, who was exploring extending the sidebar with quartodoc a couple weeks ago