qri-io / starlib

qri's standard library for starlark
MIT License
113 stars 29 forks source link

Methods should be a higher heading number than their parent type #138

Open chriswhong opened 2 years ago

chriswhong commented 2 years ago

Take the example:

  outline: xlsx
    xlsx implements excel file readers in starlark. currently a highly-experimental package
    that will definitely change at some point in the future
    path: xlsx
    functions:
      get_url(url string)
        fetch an excel file from a url
    types:
      File
        an excel file
        methods:
          get_sheets() dict
            return a dict of sheets in this excel file
          get_rows(sheetname) list
            get all populated rows / columns as a list-of-list strings

This yields the markdown:

## Functions

### get_url

\```
get_url(url string)
\```

fetch an excel file from a url

## Types

### File

an excel file

**Methods**

### get_sheets

\`\`\`
get_sheets() dict
\`\`\`

return a dict of sheets in this excel file

### get_rows

\`\`\`
get_rows(sheetname) list
\`\`\`

get all populated rows / columns as a list-of-list strings

In the qri website, this is rendered in the table of contents as:

image

File is an h3, but two methods of File are also h3. These should be h4 so they appear subordinate to File

We might also consider making methods an h4 so it will appear in the table of contents, and having the actual methods be h5, so the user can clearly see the hierarchy.