Documentação Symfony2 local em HTML , ePub e (yes!) PDF

Muitos ainda estão procurando no site da documentação do Symfony2 como baixar uma versão em PDF com existe na versão 1.4, mas infelizmente não está disponível.

Particularmente eu prefiro navegar em HTML,  mas no site evidentemente não é a forma mais ágil.

Tentando baixar a documentação manualmente (trabalho de índio) encontrei a referência ao formato utilizado, o reStrucuturedText:

Symfony – Documentation Format

E lá a orientação para utilizar o Sphinx (não o indexador, mas o gerador de documentação em Python) para gerar a documentação em HTML, Latex, ePub e em PDF.

Sem PDF até o momento (atualizado)

Mas, até o momento, não tive êxito em gerar em PDF. Aparentemente algumas extensões na sintaxe do reStrucuturedText utilizadas na documentação impedem que o rst2pdf de funcionar adequadamente. Ia tentar com o LaTeX, mas exige quase 1Gb de download para rodar a conversão para PDF (o que é pouco viável para mim no momento). Perdão, sem solução até o momento.

Atualização em 30/11/2011

Comentário do Matteo Montanari (veja abaixo) relatou sucesso para gerar o PDF com os passos no final deste documento. Grato, Matteo.

Mas com HTML navegável e ePub

Então, vamos preparar a ambiente, instalando o python e o easy_install (para instalar módulos do Python como no CPAN do Perl ou PEAR do PHP).

apt-get install python-setuptools python-dev build-essential

Depois, instalamos o sphinx-pocoo:

easy_install -U Sphinx

Próximo passo é baixar a documentação do Symfony2. A seu critério, utilize o git ou baixe o tarball direto no GitHub:

git clone https://github.com/symfony/symfony-docs.git

ou

wget https://github.com/symfony/symfony-docs/tarball/master -O symfony-docs.tar.gz

Continuarei aqui com o tarball.

Crie um diretório (a seu critério, aqui em tmp como exemplo):

mkdir /tmp/sf-docs
cd /tmp/sf-docs

Execute o Quick Start do Sphinx:

sphinx-quickstart

Os itens de preenchimento obrigatório são:

> Project name: Symfony2Docs
> Author name(s): Symfony Team
> Project version: 2.0.17

Ative também a opção para utilizar o construtor de epub:

> Do you want to use the epub builder (y/N) [n]: y

A documentação do symfony tem um detalhe interessante que é a documentação de configuração, que aparece em abas. Para dar suporte a ela, é preciso baixar uma extensão. ( (o “7196620” pode ser diferente de você, pois é gerado dinamicamente pelo GitHub).

mkdir /tmp/sf-docs/_exts
cd /tmp/sf-docs/_exts
wget https://github.com/fabpot/sphinx-php/tarball/master -O sphinx-php.tar.gz
tar xzvf sphinx-php.tar.gz
mv fabpot-sphinx-php-7196620/sensio .
rm -rf fabpot-sphinx-php-7196620/

Configure editando o arquivo /tmp/sf-docs/conf.py – procure esta linha:

extensions = []

e substitua por estas:

sys.path.append(os.path.abspath('_exts'))
from sphinx.highlighting import lexers
from pygments.lexers.web import PhpLexer
extensions = ['sensio.sphinx.refinclude', 'sensio.sphinx.configurationblock', 'sensio.sphinx.phpcode']
lexers['php'] = PhpLexer(startinline=True)
lexers['php-annotations'] = PhpLexer(startinline=True)
primary_domain = 'php'
api_url = 'http://api.symfony.com/master/%s'

Copie os fontes da documentação para este diretório (o “fac0d42” pode ser diferente de você, pois é gerado dinamicamente pelo GitHub):

cd /tmp
tar xzvf symfony-docs.tar.gz
cp -R /tmp/symfony-symfony-docs-fac0d42/* /tmp/sf-docs/

e agora é só construir a documentação!

HTML

Execute:

cd /tmp/sf-docs/
make html

e é só navegar via browser em file:///tmp/sf-docs/_build/html/index.html

Dicas: você pode personalizar o tema utilizado para gerar o CSS. Veja dicas em: Sphinx HTML theming support. Particularmente, eu utilizei no conf.py:

html_theme_options = {
"rightsidebar": "true",
"stickysidebar": "true"
}

para colocar o sidebar à direita e fixo (fica sempre visível na rolagem da página).

Se quiser utilizar a busca, coloque o diretório do HTML dentro de um virtualhost do seu servidor web (pode ser sua máquina local); assim o JS utilizado consegue buscar na documentação!

ePUB

Execute:

cd /tmp/sf-docs/
make epub

e encontre o livro eletrônico em _build/epub

Quem quiser tentar a versão em PDF…

…precisa instalar:

apt-get install texlive-full

e então:

cd /tmp/sf-docs/
make latexpdf

Eu tentei com o pacote texlive-latex-base ( que tem ~80Mb ao invés de ~930Mb do full) mas o PDF não rodou. Boa sorte e avise se conseguir.

  • got it, excellent! beautiful documentation and it worked fine. The file is only 3MB and it has all.

    Thanks!

  • Pingback: Symfony2 Learning Book | Craft It Online!()

  • Thanx, this was a great start. :-))

    Two remarks:

    a) Someone put a ready-to-go-offline html version on github:

    https://github.com/rafaelgou/symfony-docs-html-local

    b) I installed this LARGE TeX package and yes, you can render a proper PDF (522 pages) from it (drop me a line if you want a copy of it).
    I still got some warnings on missing bundle documents, but this was the same with the html version as well and I think it’s kind of normal (maybe someone else knows it?).

  • Hello Dorthe

    I have just managed to build the pdf file.
    All I needed was the full texlive (texlive-full) and then sphinx gives the latexpdf option which does the job.

    It’s pretty good result.
    I am happy with it.

  • Michaël P.

    I manage to generate pdf with the following packages (approximately 9Mo):

    texlive-common texlive-latex-base texlive-latex-recommended texlive-latex-extra

    But I have a serious problem with the epub version I generate. The epub file contain just the table of contents and the index, but content at all.

    Very frustrating!

    • fran’

      Same problem. Don’t know why ? An idea ? Thanks

  • Jack Smith

    PDFs give a good conversion quality of conversion better than a word file my own file conversion with word was very difficult, I ordered my book to conversion from http://www.ebookconversion.com/

  • toetip

    Hey !
    thanks for you tutorial.

    I got a problem with epub generation (from sf sources or even from your repo on github) : I always got a ten pages long epub.

    As a sphinx newbie, I must have miss something. Did you got the same issue ? if no, could you explain howto build ?

    thanks

  • ZoRDoK

    I too got 11 page epub – table of context only

  • Enrico Marongiu

    The .epub file is just the TOC with all the documents referenced as local html files.
    Curiously, converting the .epub in .mobi (with Calibre) I managed to obtain a fully functional and self consistent kindle-friendly ebook.
    Perhaps converting it back to .epub may be a workaround 🙂

  • Pingback: How to build a kindle friendly Symfony2 documentation ebook | Enrico Marongiu()

  • Hey there. I discovered your website the use of msn. It is really an extremely well written content. I’m going to ensure that you book mark this and are avalable back to discover more within your practical information and facts. Many thanks for the particular publish. Let me unquestionably go back.

  • Hello,

    I successfully generated an epub for Symfony Docs 2.3.4 using your method (on Windows).

    However, I have 2 small issues :
    1) https://raw.github.com/fabpot/sphinx-php/master/configurationblock.py doesn’t exist. Is it important to download it and what should be done with it ?

    2) when generating ePub, I got some warnings from sphinx :
    bundles/map.rst.inc:1: WARNING: unknown document: /bundles/SensioFrameworkExtraBundle/index
    bundles/map.rst.inc:2: WARNING: unknown document: /bundles/SensioGeneratorBundle/index
    bundles/map.rst.inc:3: WARNING: unknown document: /bundles/DoctrineFixturesBundle/index
    bundles/map.rst.inc:4: WARNING: unknown document: /bundles/DoctrineMigrationsBundle/index
    bundles/map.rst.inc:5: WARNING: unknown document: /bundles/DoctrineMongoDBBundle/index

    Thank you