Symfony-docs: add more published doc formats (pdf, epub)

[c33s]

The documentation strategy (instead of a large book, the Symfony2 documentation is split into small chapters about specific topics);
Fabien Potencier
http://symfony.com/blog/symfony2-documentation

i think, it would be very important to also create and provide the symfony2 docs in "book" form -> pdf / epub.

why?

• no, we don't have a internet connection everywhere
• ebook reader doesn't handle rst
• for people who want to print it out
• ...

of course the format of the symfony docs opens all doors to do it myself (http://symfony.com/doc/2.0/contributing/documentation/format.html),
i only need Sphinx and then i can create pdfs. wait, i have to install rst2pdf. easy

ImportError: No module named setuptools
http://www.happylife.sg/index.php/2010/04/25/importerror-no-module-named-setuptools/

and so on...

what i want to say is, that its not a 5 minute act to create a pdf and if i just want to learn a framework it doesn't mean i want to learn how to convert rst in pdf (or have the time to).

it would be a great thing, to add the conversion to pdf/epub to the docment website build/deploy process, so the problem is solved one time and the users of symfony can focus on symfony instead of building pdf files.

before anyone answer with "we don't need that", "it is ok how it is",... don't forget we are talking about digital/virtual stuff, so if i would ask to print a book in paperback insted of hardcover this would be a decision where only one way would be possible course you can if you look at the costs but in the virtual world we just can deploy both with nearly no overhead.
we don't need to choose between this or that way, we can take both ways at the same time.

to provide a one (all the docs) or three (book, cookbook, components) file(s) doc would really help to use it mobile.

please help the developers to keep focus on developing with php and symfony not sphinx and other stuff.

[c33s]

http://tech.rgou.net/en/symfony/documentacao-symfony2-em-html-local-epub-e-quase-pdf/

[franek]

+1

I am looking for the Symfony2 Documentation in epub format (to read it on my ebook reader). I have tried to convert the doc via Sphinx (cf. http://symfony.com/doc/current/contributing/documentation/format.html and http://tech.rgou.net/en/symfony/documentacao-symfony2-em-html-local-epub-e-quase-pdf/) but the epub that I have generated just contains the table of contents and the index, but not the content (bugs ? ).

[fabpot]

Everything is now available as PDFs... next stop: epub format.

[hhamon]

Yes, epub format would be great :)

[JohnAlbin]

Thanks for the PDF! It's handy to have portable docs.

But I'm eagerly waiting the epub version since the PDF is not bookmarkable, which makes it cumbersome when note taking.

I'm leaving on Friday for a Drupal sprint to re-do its theming layer for D8, so I've copied the PDF to my Kindle Fire (text size is a bit too small for the kindle since the Fire is small) and I'll be reviewing these docs on the plane. Maybe I'll have an epub version by then? :-D

[weaverryan]

+1 the PDF's look great by the way, nice job @fabot :).

[Naewis]

Hi,

Thanks for PDF's, but it seems that the render is not really great for some eReaders.
I'm interested in the ePub format too. Still planned ?

[c33s]

thx for the pdf
conversion in calibre to epub doesn't work to well. +1 for an official epub

[PhilKershaw]

ePub format of the book/docs would be very helpful. Count this as my +1

[pefferen]

+1 for ePub here aswell. I run into the same problems as Franek

[mailopl]

Another +1 for ePub, PDF is practically not readable on e-ink readers. :(

[teranex]

+1 for ePub (and Mobi for Kindle)

[pxlcore]

+1 for ePub. Please.

[robsonpeixoto]

+1 for ePub (and Mobi for Kindle)

[amiroff]

+1 for epub from mee too!

[robsonpeixoto]

The twig export the epub format. Maybe is "only" use the same script

[c33s]

@gkatsanos on http://twig.sensiolabs.org/documentation you have already a epub download. so using the same "script" to generate the epub for the symfony doc maybe would be quite easy

[c33s]

@gkatsanos please read the whole ticket.
it's not about converting pdf to epub, the base format is rst see http://symfony.com/doc/2.0/contributing/documentation/format.html
with sphinx it is possible to convert the base format to pdf and/or epub (and more).
as i opened the ticket, there was no pdf option. meanwhile the pdf download option is there (thanks for that), but epub is still missing.

hope that helped.

[wogong]

+1 for the epub version. People will appreciate it.

[wouterj]

I think it is clear that we need the epub format and I don't think it is usefull to add more useless +1 comments in here.

Just a simple ping @fabpot and wait until he gets time to do this, it is a busy time around a new release, so please be patient...

[weierophinney]

We have been publishing epub versions for ZF2, but only recently discovered that for many ereaders, only the TOC was loading. I was able to make a small change in our Sphinx toolchain to convert from epub to epub via Calibre (http://calibre-ebook.com/), and now the epub's are usable on all devices tested. (Basically, Calibre takes apart the epub and applies a number of compatibility passes to it before regenerating.)

You can see the change here: zendframework/zf2-documentation@3e11925 (look in docs/Makefile).

[fabpuc]

Another +1 for ePub

[mykiwi]

+1 for Mobi / ePub

[csvan]

+1 for ePub or Mobi

[garak]

+1 for epub :+1:

[fgm]

+1 for ePub. Maybe pandoc can help in this case ? I'm using it on other documents to build both PDF and ePub from the same source.

[lucasaba]

+1 for epub :+1:

[matiux]

+1 for epub!!

[promethean]

+1 epub / mobi

[gziolo]

+1 mobi

[mimopo]

+1 epub

[ph-il]

Epub and Mobi are Packaging of HTML version. So it should be easier to transform the rst to HTML5 then translate it to both format.

[fgm]

FWIW, Pandoc can generate both ePub, PDF and HTML from the same (variant of) Markdown source, or RST which is what the Symfony docs use, AIUI.

[kylescousin]

Please please epub this. Converting the PDF to EPUB doesn't work properly with any tool out there.
https://github.com/mattharrison/rst2epub2 - this may help

[wouterj]

@fabpot there is really a lot of interest in the ePub format. Sphinx already includes an ePub builder. It should not be too hard to implement I think.

More info:

• http://sphinx-doc.org/latest/config.html#options-for-epub-output

[cordoval]

I wonder if the versions of pdf and epub would be always current and in any version as soon as a merge to symfony/symfony-docs is made. That is as important as having it in the correct format.

[wouterj]

We already have that @cordoval Within 15 minutes after merging, the site and pdfs are regenerated

[cordoval]

ok because i was going to propose easybook for this since it has all those generators and is php rather than python. the thing is the generation is locked in the know-how that some say it shouldn't perturb devs going to the point, and the guys that may want to tweak documentation to a certain way and being able to DIY and adapt colors, frames, device support, etc. Just imo I wanted to tip that in. :baby:

[Einenlum]

Are there some news about this epub feature ?

[wouterj]

@javiereguiluz ?

[nomasprime]

+1

[gaetan-petit]

2 years and a half, we really really need this.
I tried to build it myself but the result is not quite good.

[wouterj]

ping @javiereguiluz A lot of people want this and Sphinx provides easy tools for this, is there any reason to not do this?

[gaetan-petit]

Ping @weaverryan isn't this issue a DX issue?

[wouterj]

@gaetan-petit it's a UX issue if you ask me :).

Unfortunately, Ryan and me can't do anything to fix this, other than pushing the sensio guys (just like you can do), only some of them has access to the builder tools of the docs.

[weaverryan]

This would be nice, since so many users have asked for it. @javiereguiluz I know we're doing 100 things right now, is there any plan for this? Do the comments from weierophinney on how ZF2 set this up help? https://github.com/symfony/symfony-docs/issues/1029#issuecomment-16444660

[harikt]

When downloading pdf we are mostly seeing only one format.

Eg : In Routing chapter it will be mostly showing only the annotations. Will be nice if there is an option to see every sort of code or download the ones that people like.

Eg : Show yaml format , annotations, xml, php etc. This may be hard to solve I know. But if all ways is also there is not bad.

Thank you

[zanardigit]

I setup locally the building tools required to build the epub, and got some result. It's far from perfect but it's an epub, it's got an index and you can read it, so it's definitely a good start :-)
I will see if it's possible to completely automate the build. It may take a while so don't hold your breath.
Meanwhile, please let me know if it makes sense to publish the manually built epub somewhere.

[stof]

Meanwhile, please let me know if it makes sense to publish the manually built epub somewhere.

Given that the doc itself changes on a daily basis, I don't think it makes sense (unless you rebuild it on a daily basis too)

[xabbuh]

Given that the doc itself changes on a daily basis, I don't think it makes sense (unless you rebuild it on a daily basis too)

Well, I would at least be interested how it looks like in the current state. :)

[zanardigit]

@stof ok, I will only publish it when it's fully automated.
@xabbuh feedback is welcome (although I already know there's still a lot of work to do) so I will tweet you the link

[rotten77]

Hi, I make mobi and ePub formats: http://blog.rotten77.cz/symfony-docs-for-ebook-reader

[xabbuh]

@zanardigit Sorry that I didn't reply earlier. I just converted your first attempt into the mobi format using Calibre. Looks good so far at this early state. Once you managed to navigate to a section of the docs, it reads really well. :+1: However, navigating between the different sections is really hard. So, having one file per section would probably be much more comfortable. I'll try to get my hands on an epub reader and see how it looks like in that format. Anyway, thank you really for you time spending on this! :)

[zanardigit]

@stof this version is now built automatically every day: http://symfonyepub.gibilogic.com.
P.S. it's just a temporary place, if you want me to FTP / rsync / push somewhere else, I'll be happy to,

@xabbuh I have made some steps forward just by updating the tools. Now the ebook is complete and correctly sorted, and there's no need to use Calibre anymore.

[xabbuh]

@zanardigit Well, I still need to convert it to be able to use it on a mobi-only device.

[zanardigit]

@xabbuh you're right, you still need to use Calibre. But I think that's outside the scope of this issue:

• as far as i read (see https://github.com/symfony/symfony-docs/issues/1029#issuecomment-5112493) the target was only the EPUB.
• MOBI format is not direcly supported in Sphinx so I can only assume that requires a bit more work
• converting from EPUB to MOBI via Calibre is really easy and user-friendly anyway, so it's probably not worth it to do the conversion ourselves.

Hope this makes sense! :-)

[xabbuh]

@zanardigit Of course, I didn't meant to criticise you about that. :) Having an epub book would actually be huge step at all. :)

[gaetan-petit]

@zanardigit: the result is not bad, could you add a build for french version of the documentation? thanks.

[zanardigit]

@gaetan-petit done

[gaetan-petit]

@zanardigit :+1:

[zanardigit]

So, now we have an epub built automatically each day. What are the next steps required to close this issue? More versions? More languages? Publish the epubs on Symfony website?

[gaetan-petit]

Yes, Yes, Yes.

Maybe get Sensio lab add it's css styles would be better.

[madalinignisca]

:+1: to publish on the Symfony website

[Einenlum]

:+1: @16nsk

[typomedia]

@fabpot , where is the promised epub now?

[typomedia]

Ok, this site still seems to work with daily builds: http://symfonyepub.gibilogic.com

[zanardigit]

@typomedia in fact I just noticed it's broken since a few weeks. I will fix it now, so I will also remove EOL versions and add 2.8.

[weaverryan]

Thanks @zanardigit - that's awesome. @javiereguiluz could we link to that site for people who want ePub? It's great a community member solved this, I think we can help tell people about it.

[zanardigit]

@weaverryan glad to help. Before linking to the site please wait a couple of days so that I will be able to fix (I have a Sphinx version issue due to Ubuntu repo not being up-to-date).

[javiereguiluz]

@weaverryan @zanardigit I'm sorry for telling you this and I hope you understand it well: we cannot link to this alternative version from the official website. The reason is the same we applied when we decided to not link to external blog posts: the site can be down or hacked, the content can be hacked or change without our knowledge, the site can suddenly change to include contents, ads, etc. that don't comply with our policies, etc.

We can't control a third-party website, that's why we cannot link to it. I'm only talking about "content websites". Obviously we link to official project pages, GitHub repositories, etc.

[wouterj]

@javiereguiluz so then, isn't it possible to publish epub formats on symfony.com? @zanardigit seems to have a generation script that works good, can't this be integrated into the site the same way as PDFs are integrated?

[javiereguiluz]

@WouterJ if @zanardigit kindly shares his script with me (javier.eguiluz @ sensiolabs.com) I can try to use it or adapt it for symfony.com server. I can't promise a solution, but I can guarantee that I'll try it.

[zanardigit]

@javiereguiluz as I already mentioned before in this same issue, that site was meant to be temporary and I'm totally ok with your proposal.

To make things easier for you, what if I publish the resulting epubs on a GitHub repo? You could just get them without having to setup the whole build script.

[javiereguiluz]

@zanardigit thanks for understanding this decision. To be honest it would be better to have the script, so we can add some book covers to the books and to update their styles when needed. Thanks!

[Einenlum]

@WouterJ & @javiereguiluz :+1: for having the script directly on the official website.

[gaetan-petit]

Finally :+1: make it happen @javiereguiluz !

[zanardigit]

@javiereguiluz the script is available at https://gist.github.com/zanardigit/84f0bd8f2948c57d6d2d. If you need any additional info, let me know.

P.S. the rules about the style and covers are not actually part of my script; they are in the Makefile of the documentation repo.

[ethernal]

@zanardigit I noticed that the site is missing 2.8/3.0 version of the docs, any way you could provide us the files.

I tried building the docs myself (I have no access to proper Linux machine at the moment sadly).

Also when I tried building the docs with Jinja 2.8 manually I'm getting lots of errors due to Sphinx PHP extensions. If I comment 'from string import upper' in bestpractices.py

 File "d:\dev\tools\python\3.5\lib\site-packages\jinja2\compiler.py", line 427, in fail raise TemplateAssertionError(msg, lineno, self.name, self.filename) jinja2.exceptions.TemplateAssertionError: no test named 'index'

if I then change (in layout.html in _templates dir of docs)

{% set isIndex = pagename is index %}

to
{% set isIndex = pagename %}

this error shows up

File "[...........]\python\3.5\lib\site-packages\jinja2\compiler.py", line 427, in fail raise TemplateAssertionError(msg, lineno, self.name, self.filename) jinja2.exceptions.TemplateAssertionError: no filter named 'get_type'

I have no knowledge of Python so I'm not confident about the changes I make but it seems that the extensions are not compatible with versions of software I'm using or at least I hope that's all.

Using Phyton 3.5.1
Jinja 2.8

[zanardigit]

@ethernal since @javiereguiluz asked me the script I just assumed he would go on publishing it on the Symonfy site, so I stopped managing my temporary site (and in fact I will remove it shortly). I think you should ask him about the progress of the task.

[kamilsk]

still open :(

[weaverryan]

I'll bring this up at our next docs meeting :). It's out of the hands of most of us contributors because the logic would live on symfony.com itself.

[mitas]

:+1: epub

[michaelperrin]

@mitas I opened a PR for epub: #7347

[NetaLev]

+epub

Maybe an updated epub to symfony3, please?

Thanks!

[kkarkus]

+epub

[sadok-f]

+epub

[michaelperrin]

@sadok-f Since https://github.com/symfony/symfony-docs/pull/9972 was merged, I realize it is quite easy to generate an ePub file!
Here is one that I have just generated for the master branch of the docs: http://www.michaelperrin.fr/SymfonyFrameworkDocumentation.epub

If anyone would like to know how I generated the file, feel free to ask me!

[sadok-f]

@michaelperrin Thank for the link!
(it's missing an l in the url [michael])

[michaelperrin]

@sadok-f Thanks, fixed!

[pawel-slowik]

The builder docker container currently supports and successfully builds docs in the EPUB format with make -C _build epub. I have tested the output file on a rather old e-reader (a Nook from 2011) and it is nearly perfect, with some very minor CSS issues.

I guess publishing the EPUB on the website is now mostly a matter of CI and procedural arrangements. For example, what do you do if the HTML build succeeds, but the EPUB fails? This should't really happen as Sphinx is quite reliable, but still...

For anyone wanting to generate the EPUB on their own, here's a recipe:

1) Build the documentation:

    docker build . -t symfony-docs

2) Find the builder docker image. It's the one that was created right before the symfony-docs image and has no repository name. For example:

    docker images

Output:

    REPOSITORY          TAG                 IMAGE ID            CREATED             SIZE
    symfony-docs        latest              a898d4c9dc74        25 minutes ago      155MB
    <none>              <none>              f82c133b78fc        26 minutes ago      1.12GB
    nginx               latest              5a3221f0137b        6 days ago          126MB
    python              2-stretch           62f3f5e37c61        7 days ago          916MB
    hello-world         latest              fce289e99eb9        7 months ago        1.84kB

In the above example f82c133b78fc is the ID of the builder image.

3) Reuse the builder image to create an EPUB file:

    mkdir /tmp/epub_output
    docker run -i -t -v /tmp/epub_output:/tmp/epub_output f82c133b78fc /bin/bash

Inside the container:

    make -C _build epub
    cp _build/epub/SymfonyFrameworkDocumentation.epub /tmp/epub_output
    exit

The EPUB file is now in /tmp/epub_output/SymfonyFrameworkDocumentation.epub .

[javiereguiluz]

We have an important update about this issue.

During the past SymfonyCon Amsterdam 2019 conference, the Symfony Docs Team held a meeting to discuss about Symfony Docs and make some decisions.

One of the most important decisions that we made was to no longer support alternative formats such as PDF (and to not introduce new formats such as ePub). The main reason was that we don't have the resources to make this work as good as it should work. The second reason is that most of Symfony developers don't need that because they have a reliable Internet connection whenever they need to look for the Symfony Docs. A final reason is that given the huge activity of this repository, any downloaded PDF/ePub doc is "wrong" (contains bugs or it's incomplete) just a few hours after being downloaded (so you need to download it again continuously).

In addition to closing this issue, we're locking it. We rarely lock issues, but this kind of decisions usually lead to heated reactions, so we'd like to prevent that. If you want to freely express your opinion about this (including your strong disagreement, if that's what you think), please use Symfony's Slack: https://symfony.com/slack Thank you!