Kubebuilder: Build proper PDF and EPUB versions of the book

[daenney]

The kubebuilder book is only available in online form at https://book.kubebuilder.io/. This makes it hard to consume the documentation in any other way than online, via a laptop or mobile device. Though it's possible to use the print function to get to a PDF with all the content, a lot of things in the generated PDF are broken:

• All the links don't work, they only retain the styling, not the linking
• There's no TOC, making it awkward to navigate the document
• All the hidden sections/output are not expanded or expandable

There is a plugin for mdBook that should make it possible to generate an EPUB to make it more easy to have an offline version of the book that can be loaded on e-readers. Though the maintainer of the epub plugin appears to no longer be able to spend time on it, other community members are stepping in to maintain and improve it. An alternative could be to look at using pandoc instead to take the Markdown and generate a PDF and EPUB that way.

[blandger]

just FYI
In TRPL book case and other books that contain linked code sources like

{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-01-cargo-new/src/main.rs}}

pandoc is not able to build correct epub/pdf versions.

[kensipe]

For awareness... asciidoc might be the way to go...it will allow for better references of code. asciidoctor will publish to html, pdf, pandoc, mobi, and epub

a quick review... I imagine some refactoring of docs will be necessary to support

[blandger]

I've solved problem of processing links like:
{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-01-cargo-new/src/main.rs}}
and built several MD books as EPUB using custom release version.

[blandger]

I've checked local, custom code for composing the epub from the book sources. Book looks ok, but the links look different so they are not processed by current code.
{{#literatego ./testdata/project/api/v1/groupversion_info.go}}
instead of rust style:
{{#rustdoc_include ../listings/ch02-guessing-game-tutorial/no-listing-04-looping/src/main.rs:here}}

The Kubebuilder Book-en-0.0.1.zip

[blandger]

All
I replaced local links from :
{{#literatego ./testdata/project/api/v1/groupversion_info.go}}
to another hash #include supported by mdbook-epub so they look as :
{{#include ./testdata/project/api/v1/groupversion_info.go}}

and that gave ability to build epub book WITH go sources included. So now book version look more or less correct. See attachment,
The Kubebuilder Book-en-0.0.2.zip

[camilamacedo86]

Hi @blandger,

WDYT about push a PR with your solution? @daenney could you help us to review and check his PR to see if it could attend your request here?

[blandger]

Hi @camilamacedo86
That is a extremely hard question, because there are thee different rust libraries involved in patching 'mdbook-epub' tool to be working and generating proper epub from MD sources.

1. Several patches/PRs I've prepared inside 'mdbook-epub' and I have a 'maintenance rights' for that repo. Although review is very long by initial library author. The first PR is in review - https://github.com/Michael-F-Bryan/mdbook-epub/pull/37
2. Fix is not possible without patching 'mdbook' library (depends on changes for that). That library is maintained extremely slow. You can see number of PRs and Opened Issues there. I think my path will be accepted withing several years unfortunately. I haven't created PR for it yet. But I see a small chances to push prepared changes there. That is most hard part. https://github.com/rust-lang/mdBook/pulls
3. A small patch is not accepted by epub-builder : https://github.com/lise-henry/epub-builder/pull/15

As I think the most probable variant in creation statically built release version of my custom 'mdbook-epub' code version for Linux and Windows (I don't have a Mac) and publish that as is on GitHub only.

[fejta-bot]

Issues go stale after 90d of inactivity.
Mark the issue as fresh with /remove-lifecycle stale.
Stale issues rot after an additional 30d of inactivity and eventually close.

If this issue is safe to close now please do so with /close.

Send feedback to sig-contributor-experience at kubernetes/community.
/lifecycle stale

[daenney]

/remove-lifecycle stale

[daenney]

Sorry for my lack of response on this. I took a look at the 0.0.2 archive that was uploaded. It's already a lot better, so thanks very much for that!

There's still a few things that make it hard to consume the current output. The table of contents doesn't work, everything links to page 1, and similarly with most links to other chapters within the book don't go anywhere.

The code samples are also a bit messed up now. It appears newlines aren't respected, so everything's wrapped / on the same line making those really hard to read. This might just be a stylesheet problem.

One very minor thing is that each section starts on its own page, but some sections are really short so you end up with a page that 90% blank. I'm not sure if there's an easy way to fix that, but it might be nice to pack subsections and only start chapters on their own page.