ExDoc: long module names in sidebar getting clipped -> what to do?

Questions / Help
1

I’m in the end stages of writing an API wrapper (code) for the API provided here and am struggling to provide a nice documentation experience for potential users.

For lack of a better name, the wrapper will be called ScrapyCloudEx. As you can see in the linked documentation above, the API endpoints are split across 2 areas: “app” and “storage”. These change the API calls to some degree (e.g. pagination options are different in app and storage).

I wanted my wrapper to closely follow the API documentation (so it’s easier for the user to know which function maps to which API endpoint), and each endpoint wrapper is therefore implemented in its own module such as ScrapyCloudEx.Endpoints.Storage.Items.

My issue is that this is a very long and cumbersome name. When coding this isn’t an issue (using e.g. alias among other options), but it becomes a problem when viewing the documentation generated by ExDoc: the module names in the sidebar get clipped because they are too long.

What’s the best way to address this? Is there a way to provide some sort of “alias” for the value displayed in the sidebar? Should I create a new module with a shorter name that just defdelegates to the actual implementation (e.g. ScrapyCloudEx.Items defdelegateing all public functions to ScrapyCloudEx.Endpoints.Storage.Items)? Some other approach?

3 Likes
2

There is an open issue here: https://github.com/elixir-lang/ex_doc/issues/834

2 Likes
3

Excellent, thank you. I’ll monitor that issue :+1:

2 Likes
4

Btw, if you would like to give it a try, let me know and I would love to provide guidance. :slight_smile:

I think the simplest approach is to treat each nesting alias as its own “groups_for_modules”. So when you do nest_module_aliases: [Foo.Bar], it is the same as setting groups_for_modules: ["Foo.Bar": [Foo.Bar.Baz, Bar.BazBat]].

1 Like
5

I’d love to give it a try if nobody is working on it. I’ll look through ExDoc later today and see what I can come up with.

1 Like
6

Just a tip: if you start looking for the elixir code that renders the sidebar you’ll find out it doesn’t exist. The sidebar is rendered in javascritpt in a handlebars template somewhere. This might save you some time looking.

3 Likes
7

I don’t think there is. :slight_smile: Go ahead!

1 Like
8

So I’ve taken a first stab at an implementation, which is available for comment here and I would love your feedback on what I have so far.

No tests or docs yet, as I want to ensure I’m on the right track first…

Also, how do you prefer to work in case there are several iterations? Should I keep the work in my private repo and only open a PR on ExDoc once it’s more or less finalized, or would you rather I open a PR on the ExDoc repo even if more work must be done on the branch?

2 Likes
9

Feel free to open up a PR as early as you want so you can collect feedback. :slight_smile:

2 Likes
10

For completeness and curious spectators :grin:, here’s the PR

2 Likes