EPUB styles

[milmazz]

Hello @elixir-lang/exdoc

I will try to fix all the issues reported by epubcheck after producing the EPUB document for elixir-lang/elixir/ this week that I have some time, but I was wondering if there is any volunteer that could help me improving the CSS styles for the EPUB document.

I would like to see something as polished as the EPUB document for the Swift programming language:

Any help is more than welcome :)

[josevalim]

Is the swift epub open source? If so, we can check the license of the CSS files and see if we are allowed to use them. If so, we can add it and do some modifications to it (minor ones, like making the border light purple?).

[milmazz]

@josevalim Yes, the Swift EPUB use these three CSS files from the Sphinx team (BSD license):

• epub.css_t
• basic.css_t
• pygments.css

[josevalim]

I believe we can use them then. We just need to make sure to keep the notices in the .css files when we copy their contents!

[cgerling]

I was searching for open issues and found this one.
Is this still something to be addressed?

[josevalim]

Yes, it is!

[cgerling]

Cool, I was looking at the suggested approach and there are a lot of incompatibilities between the referenced CSS files and the HTML structure that ex_doc produces:

• the reference CSS doesn't support different types of admonition blocks, those blocks are always rendered as "Notes", which would be equivalent to ex_doc's neutral one.
  I think that would be good for such blocks to have different styles based on their type, the same way we have on the Web.
• the reference CSS is somewhat compatible with code blocks, the major issue is with the line numbers, the CSS expects for each line to be contained within a li.
  Also, I was trying to replicate the line numbering for the makeup output but I couldn't find a way to distinguish between a regular whitespace and a line break as both are always rendered as a span.w, I would need to patch makeup to add a distinction between those two types of whitespace in order to support the line numbering.

Considering the issues described above and the assumption that most of the imported CSS won't be used, I think it might be easier to create a CSS specific for ex_doc rather than importing an external CSS.
@josevalim do you have any issues with going with that approach instead of the original one?

[josevalim]

Yes, take any approach you'd like. :) I agree that we shouldn't import the CSS as is and maybe not even all of it. Whatever we can do to improve the current one is great though. :)

[josevalim]

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.

[cgerling]

Sorry, didn't have much spare time recently but I do have most of the styling for the code blocks, including the line numbers. The only issue is that the numbering is not reliable because there is no way to distinguish newlines from whitespace in the makeup output