Project Type: Book (Fix Broken Links)

s2t2 commented 3 months ago

Hi, this auto-documentation feature is awesome, and works great for me when I am using a "website" quarto project type.

However when I use the "book" quarto project type, I notice the index table shows up, but the links no longer work, and the linked content doesn't show up in the book PDF either.

I was wondering if you have any guidance about getting quartodoc to work with the "book" project type.

I think there may be an issue with the links pointing to .qmd instead of .html, and also the .html files not getting generated.

Thank you!

Details

Book Project Type

Here is my quarto config yml file for book project type:

project:
  type: book

book:
  title: "My Quarto Book"
  author: "Your Name Here"
  date: "6/10/2024"
  chapters:
    - index.qmd
    - about.qmd
    - article.md
    - python-example.qmd
    - demo-notebook.ipynb
    - reference/index.qmd

bibliography: references.bib

format:
  html:
    theme: cosmo
  pdf:
    documentclass: scrreprt
  epub:
    cover-image: cover.png

quartodoc:
  package: my_project
  dir: reference
  sections:
    - title: Some functions
      desc: Functions to exemplify auto documentation.
      contents:
        - calculator.Calculator
        - formatter.to_usd

Broken links with "book" project type (seems like href points to a .qmd file instead of .html file):

Here is my generated "reference/index.qmd" file with links to the autodocumentation pages:

# Function reference {.doc .doc-index}

## Some functions

Functions to exemplify auto documentation.

| | |
| --- | --- |
| [calculator.Calculator](calculator.Calculator.qmd#my_project.calculator.Calculator) | The Calculator class. Use for basic math. |
| [formatter.to_usd](formatter.to_usd.qmd#my_project.formatter.to_usd) | Formats number as USD with dollar sign, two decimal places, and thousands separator. |

Looks like when I build the autodocumentation, the corresponding HTML pages (e.g. "reference/calculator.Calculator.qmd") no longer get generated to "_book/reference" directory. There is just the "reference/index.qmd" file in there.

Website Project Type

Here was my working quarto config yml for a website project type:

project:
  type: website
  output-dir: _build

website:
  title: "This is a site"
  navbar:
    left:
      - href: index.qmd
        text: Home
      - about.qmd
      - contact.md
      - python-example.qmd
      - demo-notebook.ipynb
      - reference/index.qmd

format:
  html:
    theme: cosmo
    toc: true

quartodoc:
  package: my_project
  dir: reference
  sections:
    - title: Some functions
      desc: Functions to exemplify auto documentation.
      contents:
        - calculator.Calculator
        - formatter.to_usd

Working links with "website" project type:

machow commented 3 months ago

Hmm.. I'm not sure what's happening. I created a small book example, with some quartodoc items in the reference, and it seemed to work okay when I ran...

quartodoc build
quarto preview

This is with quarto 1.4.549. Here's what I used (note I left in the generated reference folder):

book.zip

s2t2 commented 3 months ago

Hi @machow I appreciate the reply.

I cleared the references directory and re-ran the following commands, and the quartodoc command does add all the files, but unfortunately the links from the index to the other files are still broken (pointing to .qmd URLs).

quartodoc build --config docs/_quarto.yml
quarto render docs/

They are also broken when I run quarto preview docs/

My quarto version is 1.4.554.

My code is in this PR.

machow commented 1 month ago

shoot, exploring a bit more -- I wonder if quarto books require the things being linked to to be listed in chapters? When I add the API Reference pages to chapters: I'm able to click the links and see the rendered HTML.

So for example adding this to _quarto.yml...

book:
  title: "My Quarto Book"
  author: "Your Name Here"
  date: "6/10/2024"
  chapters:
    - index.qmd
    - reference/index.qmd

    # Added this page ----
    - reference/MdRenderer.qmd

machow commented 4 weeks ago

Closing the loop on this handy discussion you raised on quarto, and an issue that came out of it!

Let's re-open this issue if more is needed on the quartodoc side to make it work

machow / quartodoc