HexDocs sidebar - categories

[folospior]

Carried over from #5455

Categories

The sidebar currently divides links into:

• Pages
• Links
• Modules
• Values (shown after selecting a module)
• Types (shown after selecting a module)

Values and types are sorted alphabetically, which might not always be the best solution.

It might be useful to split documentation into categories, like:

Rooms
├─ Room
├─ delete_room
├─ new_room
Users
├─ User
├─ modify_user
├─ new_user

A custom example of this can already be found in the iv library: https://hexdocs.pm/iv

Custom categories in iv

Syntax proposals

Categories are awesome, but how do we split values into categories?
I have a few ideas for the syntax, but feel free to drop your own:

Proposal 1 (doc comments)

Using a special doc comment syntax:

/// [[category:Users]]
pub type User

/// [[category:Users]]
pub fn get_users() -> List(User) { todo }

Proposal 2 (attributes)

Using a new attribute:

@category("Users")
pub type User

@category("Users")
pub fn get_users() -> List(User) { todo }

Personally, I think a new attribute is a better choice, since adding new attributes does not constitute a breaking change. There is a very slight possibility that someone actually has [[category:x]] in their doc comments, and this would break their documentation.

Let me know what you think!

[acandoo]

I've been thinking about metadata for functions in general, and I personally also like keeping everything as attributes. However, another approach that could be taken is with a TOML frontmatter (YAML is more common, but I'd assume Gleam would want TOML):

/// +++
/// category = "Users"
/// +++
///
/// A user.
pub type User

/// +++
/// category = "Users"
/// +++
///
/// Get current users.
@external(javascript, "./user_ffi.mjs", "getUsers")
pub fn get_users() -> List(User) { todo }

The distinction between documentation metadata and attributes gets murky quickly with @Deprecated, and it also doesn't look quite as clean as having everything as attributes imo. Also, /// +++ is a lot of boilerplate.

---

Another thing to consider is if module-level categories are worth pursuing. Folders existing make me think not at all, and it's a matter of the current Docs UI better laying out modules by folder. The attribute syntax would lead to really weird-looking code imo:

//// This module provides types and functions for dealing with users in the backend.
@category("Backend")

/// A user.
@category("Users")
pub type User

// rest of the code...

[lpil]

How could the categories be ordered?

[folospior]

I think alphabetical is fine, we already sort definitions alphabetically.
I'd do: Categories sorted alphabetically -> inside the category, sort definitions alphabetically

[acandoo]

For precedent, Obsidian sorts alphabetically without configuration and most users settle on using numbers or emojis at the beginning of folders for custom ordering. I don't think there's a need for anything more complicated.

[renatillas]

I think this idea would be fantastic on some apis I'm building! Currently I'm resorting to custom script tags on the module documentation that are cumbersome to maintain. Adding this feature would definetly improve the readability of our hexdocs and improve the DX of those that want readable documentation.