nested hrefs not set as draft

[paciorek]

Not sure if this is intentional, but if I have a nested hrefs in the docs stanza, it doesn't put the nested ones (e.g., note.html below) into draft-list.yml.

E.g.,

          docs:
            - type: "Lecture"
              id: "2"
              name: Pandas 1
              href: "./units/unit2.html"
            - type: "Participation"
              id: "2"
              name: Lecture Participation 2
              href: "./units/part.html"
              auxil:
                id: "Note 2"
                href: "./units/note.html"

[andrewpbray]

Thanks for the issue and apologies that it's taken so long to respond (I didn't realize I hadn't been "watching" this repo).

This functionality wasn't intentionally disallowed, I just had conceived on this use case. Here are two different things that should work:

# take 1
          docs:
            - type: "Lecture"
              id: "2"
              name: Pandas 1
              href: "./units/unit2.html"
            - type: "Participation"
              id: "2"
              name: Lecture Participation 2
              href: "./units/part.html"
           - type: "Note"
              id: "2"
              href: "./units/note.html"

# take 2
          docs:
            - type: "Lecture"
              id: "2"
              name: Pandas 1
              href: "./units/unit2.html"
            - type: "Participation"
              id: "2"
              name: Lecture Participation 2
              href: "./units/part.html"
              note: "Don't forget to participate!"

What exactly is the contents of Note? How would you like it to appear in the HTML? (I assume this structure is for ease of schedule formatting?)

[paciorek]

Finally following up on this as I get back into trying to set up scheduled-docs functionality in our SCF/CDSS course-site-quarto template. This is not exactly the issue that was originally filed but I think it's close enough to make sense adding this here.

In that template, we have a schedule set up that mimics some of the DS courses, where each row in the schedule can have some optional auxiliary links (see [https://berkeley-cdss.github.io/course-site-quarto](this example)).

The underlying yml information looks like this, so there are nested hrefs (in the auxil stanza) that need date/draft keys.

scheduled-docs:
  draft-after: 8/24/24
  timezone: "-07:00"
  debug: true
  schedule:
    - week: 1
      days:
        - date: 8/23/24
          docs:
            - type: "Lecture"
              id: "1"
              name: Introduction
              href: "units/unit1.qmd"
              auxil:
                items:
                  - id: "Note 1"
                    href: "https://berkeley.edu"
                  - id: "Note 2"
                    href: "https://berkeley.edu"
            - type: "Participation"
              id: "1"
              name: Lecture Participation 1
              href: "https://berkeley.edu"

A few comments:

1. @andrewpbray What are your thoughts at the moment about a use case like this? Are you expecting this to work?
2. When I do this, it actually somewhat gives the behavior I want, namely setting up date and draft keys for each auxil item. And it sets date and draft for the 'outer' docs as well. So I can use the resulting generated yml with my ejs template and it works fine. Great.
3. However, it injects some additional (duplicated) key-value pairs, into the nested structure in the generated schedule.yml like this:

- week: 1
  days:
    - date: 8/23/24
      docs:
        - type: Lecture
          id: '1'
          name: Introduction
          href: units/unit1.qmd
          auxil:
            items:
              - id: Note 1
                href: 'https://berkeley.edu'
                date: 8/23/24                            # GOOD
                type: Lecture                             # WHOOPS
                name: Introduction                  # WHOOPS
              - id: Note 2
                href: 'https://berkeley.edu'
                date: 8/23/24                              # GOOD
                type: Lecture                              # WHOOPS
                name: Introduction                  # WHOOPS
            date: 8/23/24                       # WHOOPS
            type: Lecture                        # WHOOPS
            id: '1'                                     # WHOOPS          
            name: Introduction           # WHOOPS
            href: units/unit1.qmd       # WHOOPS
          date: 8/23/24                       # GOOD
          draft: false                            # GOOD
        - type: Participation
          id: '1'
          name: Lecture Participation 1
          href: 'https://berkeley.edu'
          date: 8/23/24
          draft: false

So it seems to propagate unexpected key-value pairs downwards. I'd be happy to help with fixing this if indeed this is something that should work and this is indeed a bug.

[paciorek]

@andrewpbray and I discussed this. The propagation is intentional. A user can simply ignore the unneeded key-value pairs in the generated schedule.yml. (And indeed a user might not even realize they are created...)

[andrewpbray]

Thanks for putting this note here. Another thing that informed this design choice: this is actually how Quarto works with metadata that is inherited either from a _metadata.yml stored in the subdir or the project-wide metadata stored in _quarto.yml. All the keys are propagated so that, when programming on an individual document (i.e. writing a lua filter), you have access to all of it. I've run into a few instances of keys that were not propagated due to some ... opinionated choices that were made in the design of the knitr package back in the day and it's been a serious bummer.

[andrewpbray]

Here's an example where that propagation is handy:

    - week: 8
      unit: Generalization
      days:
        - topic: "Probability Workshop"
          display-date: Oct 14
          due-tomorrow:
            - Nothing!
        - topic: "Probability Distributions"
          display-date: Oct 15/16
          date: 10/15/24
          before-class:
            date: 10/11/24
            docs:
              - type: Notes
                href: 3-generalization/03-probability-dsns/notes.qmd
          in-class:
            docs:
              - type: Slides
                href: 3-generalization/03-probability-dsns/slides.qmd
              - type: WS
                href: 3-generalization/03-probability-dsns/ws.qmd

This allows me to write an ejs filter that produces on the course calendar:

At one point I was considering indicating on the calendar which unit we were in with color (coloring the squares a slightly different color). This would be possible because of the available of the unit: Generalization key on every daily topic item.

The propagation also helps with the date/draft mechanism. We always release the notes for Tues/Weds class on the previous Friday. That's reflected in yaml by adding an additional date under before-class. So any children docs of Probability Distributions will have date: 10/15/24 unless it's overwritten by a date key that appears as a more-recent ancestor.