Checkmk / checkmk-docs

Checkmk user manual
https://docs.checkmk.com
29 stars 129 forks source link

Can we get a book version of the docs as epub and pdf please ? #31

Closed grepmeister closed 1 year ago

grepmeister commented 2 years ago

Can we get a book version of the docs as epub and pdf please ?

I would like to read all the docs on my ebook reader. Like a book.

Since this is asciidoc(tor) this should be easy to implement, shouldn't it ?

godspeed-you commented 2 years ago

As asciidoctor is not able to convert xref links to references for pages in the same document, it is not that easy to implement. Basically, we would need to implement this feature on our own. The same goes for the section of related articles.

bili123 commented 2 years ago

This is definitly not an official recommendation but maybe quick and dirty is better than nothing ;)

You can build at least a PDF version pretty easily - if you can live without inline images (icons), some Checkmk specific formatting and internal links and with some not well formatted tables. But all in all it looks pretty good, images, TOC, terminal sessions, and so on work.

So, this is a quick & dirty solution I used with Bash on Windows: You need to install asciidoctor and asciidoctor-pdf (gem install ...), clone the Checkmk Docs repo and then for some reason asciidoctor-pdf wants images and asciidoc files in the same directory. You could just copy the contents of the "de" directory to the "images" directory if you don't plan to work on the repo. I copied everything to a separate "testingcmkpdf".

Then you can use the file "menu.asciidoc" to render the whole handbook in the original order. With a little but ... Instead of a list of HTML links ("- link:foobar.html[this is foo]") you need includes like "include::foobar.asciidoc[this is foo]" - which is done quickly with sed:

sed -i 's/- link/include:/ ; s/\.html/\.asciidoc/' testingcmkpdf/menu.asciidoc

And then you can build the PDF:

asciidoctor-pdf testingcmkpdf/menu.asciidoc

You'll geht a whole bunch of warnings about already used IDs, problems with some formatted texts and much more - and a 122 megabyte PDF with over 1.400 pages.

Again, just a quick and dirty way producing something non-official. Probably more useful to just convert single files or a small subset. Maybe there's a better way, but this worked for me first try, so I didn't try further.

I've never tried to do something like this with epub - it seems possible, with some effort, according to Asciidoctor: https://asciidoctor.cn/docs/convert-asciidoc-to-epub/ But have in mind, as @godspeed-you mentioned, not everything is implemented.

Here's a preview image: checkmkdocspdf_preview

grepmeister commented 2 years ago

Hello, @godspeed-you I do not need "xref links to references for pages in the same document". I would like to read the whole documentation in a sequence without jumping around.

Just page for page like a "real" book. I am totally fine to go without any links at all.

@bili123 thank you for your suggested procedure. I am already getting nice results which are sufficient for me. As soon I implemented a good procedure how to generate a epub I'll post it here.

So far I did:

docker pull asciidoctor/docker-asciidoctor
alias ad="docker run -it -v \$PWD:/documents/ asciidoctor/docker-asciidoctor"
git clone ....
cd checkmk-docs
sed 's/- link/include:/ ; s/\.html/\.asciidoc/' < de/menu.asciidoc  > de/das-checkmk-handbuch.asciidoc
cd de
ln -s ../images .
ad asciidoctor-epub3 -a imagesdir=images de/das-checkmk-handbuch.asciidoc

$ git diff diff --git a/attributes/global_attr.adoc b/attributes/global_attr.adoc index 7a2dad34..82fcb2c4 100644 --- a/attributes/global_attr.adoc +++ b/attributes/global_attr.adoc @@ -20,11 +20,11 @@ :CMKTITLEDE: Das offizielle {CMK} Benutzerhandbuch :CMKTITLEEN: The official {CMK} user guide

-:CRE: pass:q,m[image:CRE.svg[CRE,title=Checkmk Raw Edition,width=20] Checkmk Raw Edition] -:CFE: pass:q,m[image:CFE.svg[CFE,title=Checkmk Enterprise Free Edition,width=20] Checkmk Enterprise Free Edition] -:CSE: pass:q,m[image:CSE.svg[CSE,title=Checkmk Enterprise Standard Edition,width=20] Checkmk Enterprise Standard Edition] -:CME: pass:q,m[image:CME.svg[CME,title=Checkmk Enterprise Managed Services Edition,width=20] Checkmk Enterprise Managed Services Edition] -:CEE: pass:q,m[image:CEE.svg[CEE,title=Checkmk Enterprise Editions,width=20] Checkmk Enterprise Editions] +//:CRE: pass:q,m[image:CRE.svg[CRE,title=Checkmk Raw Edition,width=20] Checkmk Raw Edition] +//:CFE: pass:q,m[image:CFE.svg[CFE,title=Checkmk Enterprise Free Edition,width=20] Checkmk Enterprise Free Edition] +//:CSE: pass:q,m[image:CSE.svg[CSE,title=Checkmk Enterprise Standard Edition,width=20] Checkmk Enterprise Standard Edition] +//:CME: pass:q,m[image:CME.svg[CME,title=Checkmk Enterprise Managed Services Edition,width=20] Checkmk Enterprise Managed Services Edition] +//:CEE: pass:q,m[image:CEE.svg[CEE,title=Checkmk Enterprise Editions,width=20] Checkmk Enterprise Editions]

:RE: Raw Edition :FE: Free Edition @@ -32,8 +32,8 @@ :ME: Managed Services Edition :EE: Enterprise Editions

-:cee-only: pass:q,m[image:CEE.svg[class=icon-left]] -:cre-only: pass:q,m[image:CRE.svg[class=icon-left]] +//:cee-only: pass:q,m[image:CEE.svg[class=icon-left]] +//:cre-only: pass:q,m[image:CRE.svg[class=icon-left]]

But I am happy now, I have a ~ 1800 pages checkmk ebook which I can now read at the beach.