elixir-lang
Epub issues
I have come across issues with the generated EPUB documentation: /cc @milmazz
-
[ ] 1. The table of contents menu, should have a tree structure like the HTML version. At the moment, the first page shows it right, but when in the reader I choose to open the TOC, it shows a flat list.
-
[ ] 2. The TOC page and the TOC element, should take into consideration the --config option to structure the items.
-
[x] 3. Internal links. https://github.com/elixir-lang/ex_doc/issues/1057#issuecomment-513113750
-
[x] 4. Deprecated notice is missing. For example in the Behaviour module, the "This module is deprecated. Use @callback and @macrocallback attributes instead." message is missing.~~ https://github.com/elixir-lang/ex_doc/issues/1057#issuecomment-513117084 PENDING: the deprecation message needs a different background color, or border.
-
[x] 5. Attributes such as since, or when the function is a macro are missing.
-
[ ] 6. Can we make smaller the gap between a function signature and a function spec?, it's like a full line empty and it looks a bit odd.
- the TOC page and the TOC element, should take into consideration the
--configoption to structure the items.
- Internal links.
Does it make sense to have them?
- "Anchor for this section" looks too big. I guess it could be removed, since AFAIK we cannot link from anywhere.
- "link to this function" doesn't look as bad, but I see no use for it.
- Deprecated notice is missing. For example in the Behaviour module, the "This module is deprecated. Use @callback and @macrocallback attributes instead." message is missing.
- Attributes such as
since, or when the function is amacroare missing
Thanks @eksperimental!
PS: btw, I have enabled Two factor auth organization wide for security but you don't have it enabled. They should have sent you an e-mail. Once you enable it, please let me know, I believe I need to give you access again.
@josevalim Yes, I got that email by GitHub, Thank you for letting me know. I need to fix my phone and I don't have the time and energy for that now. So it will have to wait for a bit. I will drop you an email when once I have enabled that. Thank you for letting me know.
@eksperimental Could you please update this issue with the things that are still pending to fix?
Thank you @milmazz , here's the updated report
- still happening
- still there
- fixed
- fixed, but the deprecation message needs a different background color, or border.
- fixed
- can we make smaller the gap between a function signature and a function spec?, it's like a full line empty and it looks a bit odd
@eksperimental can you please resubmit this issue using checkboxes in the issue for everything that is still valid? PRs are welcome, as EPUB is HTML. Thank you!
Edit: btw, I deleted the off-topic comments related to org permissions. :)
can you please resubmit this issue using checkboxes in the issue for everything that is still valid?
Updated and checked
Now that Erlang support in ExDoc is almost complete, we are gearing towards v1.0. So if someone would like to pick this up, it would be awesome.
Now that Erlang support in ExDoc is almost complete, we are gearing towards v1.0. So if someone would like to pick this up, it would be awesome.
Let me see what issues are still around, and I'll try to catch up with the code and help fix bugs.
Can we make smaller the gap between a function signature and a function spec?, it's like a full line empty and it looks a bit odd.
It probably is about personal preferences, but I don't mind the current spacing. The following is on Apple Books:
From the table of contents, ~it seems that we're considering the groups_for_extras option:~ (EDIT: No, after inspecting the code, we're just iterating the config.extras; and in the case of the Elixir docs, it matches correctly with the different sections, but we definitely need to handle the case for groups_for_extras too)
But we're ignoring the details for groups_for_modules:
So, I will work on this issue first.
In the table of contents for the EPUB version, we prioritize the extra files, and then we render the modules and the mix tasks.
But in the HTML version, the Modules tab seems to have a "higher" priority than the extras or pages because is selected.
Is that okay, or should we change how we arrange the documents in the EPUB version to keep some consistency between both formats?
@milmazz I am glad to go with whatever decision you believe makes the most sense here. :)
Deprecated notice is missing. For example in the Behaviour module, the "This module is deprecated. Use @callback and @macrocallback attributes instead." message is missing.
While I will prefer to see the following note in a more prominent background, I think this bug is already fixed.
Attributes such as since, or when the function is a macro are missing
This too seems to be fixed.
"Anchor for this section" looks too big. I guess it could be removed, since AFAIK we cannot link from anywhere.
I don't see these links anymore. Fixed?
"link to this function" doesn't look as bad, but I see no use for it.
I don't see these either.
@eksperimental If you have any spare time, could you please close this ticket and open new ones but one ticket per issue? The way this is now arranged is difficult to track. I will work on setting up a new background for the deprecation note, so, you can skip creating that one. Thanks.
I will work on setting up a new background for the deprecation note, so, you can skip creating that one. Thanks.
Interesting that when I change the appearance to "light" on Apple Books the deprecation background is nice and clear, so, I will investigate how we can provide multiple "themes" for the EPUB clients.
@milmazz I am glad to go with whatever decision you believe makes the most sense here. :)
Thanks, I'm happy with what we have after https://github.com/elixir-lang/ex_doc/pull/1850 but I'm open to hear other opinions =)