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.
Pingback: Symfony2 Learning Book | Craft It Online!()
Pingback: How to build a kindle friendly Symfony2 documentation ebook | Enrico Marongiu()