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...