Todos os textos do blog são gerados usando uma ferramenta chamada pweave, que permite escrever textos alternando markdown (ou HTML, Latex e reST) e código em Python. Apesar de ser parecido com o Jupyter Notebook, o foco do Pweave é na criação de relatórios e não na execução de código ao mesmo tempo que o texto é editado. Quando um documento é compilado pelo Pweave seu código é executado e um documento de saída é criado com os resultados. Isso facilita muito a edição dos textos, pois podemos usar nosso editor favorito ao invés da interface web do Jupyter (ela não me agrada, mas isto é bem pessoal...).
A instalação do Pweave pode ser feita via conda
conda config --add channels mpastell
conda install pweave
ou fazendo download do código a partir do PyPI. A página inicial do Pweave cite um problema com a instalaçõa via pip e Python 3. Não sei se este problema ainda existe, então pode valer a pena investigar.
Pweave pode ser utilizado de duas maneiras: convertendo um texto em markdown com código Python (usando o comando pweave) ou convertendo um script Python com comentários contendo texto em markdown (usando o comando pypublish). Ambos suportam as praticamente as mesmas funcionalidades, mas dependendo do uso um pode ser mais conveniente que o outro. Eu prefiro o primeiro modo para escrever os textos do blog.
Opções de entrada
Documentos são compostos por dois tipos de trechos (chunks): documentação e código. Trechos de documentação não são processados pelo Pweave e são copiados diretamente para a saída. Trechos de código (code chunks) são executados pelo Pweave e sua saída é colada no documento de resultado. É possível adicionar opções que controlam como a saída é processada. As que mais uso são:
fig=True: cola figuras do matplotlib no documento;caption='': legenda de figuras;source='': carregar o código deste chunk de um arquivo;evaluate=False: somente mostrar o código, sem avaliar;engine='python'|'shell': executar código em Python ou comandos no terminal.
Todas as opções de configuração de code chunks podem ser consultadas aqui.
Opções de saída
A transformação dos trechos de código no documento de saída depende do formato utilizado. Veja abaixo uma lista dos formatos mais comuns:
markdown: Produz texto em markdown na saída (em formato pandoc);md2html: Produz documento HTML a partir de uma entrada em markdown (usando o módulo markdown);pandoc2html: Markdown para HTML usando pandoc;pandoc2latexMarkdown para Latex usando pandoc;rest: Documento em Restructured Text.
Mais formatos de saída em Latex podem ser vistos na documentação oficial). Também são suportados outros formatos mais obscuros.
Um ponto importante é que os formatos que exportam HTML suportam equações escritas no formato Latex usando MathJax. Logo, é possível criar textos bastante técnicos e exportar diretamente para HTML (além de Latex,é claro). Um exemplo é o texto que fiz sobre Regressão Logística.
Usando Pypublish
O comando pypublish recebe um arquivo em Python como entrada e devolve um documento formatado. Toda linha de comentário começando com #' é incluída como markdown no documento formatado. O restante do código é executado. Opções para a visualização do código podem ser definidas usando #+. Veja abaixo um exemplo de script que pode ser publicado usando pypublish.
#' % título
#'% author
#'% data
#'este texto é um exemplo em markdown para pweave.
print('hello!')
var = 7
#' O valor de var é <%= var %>!.
#' Abaixo um gráfico (com legenda!). O código usado para gerar o
gráfico não aparece no resultado final.
#+ caption='Gráfico com legenda.',echo=False
import numpy as np
import matplotlib.pyplot as plt
plt.plot(np.random.rand(10), '-')
plt.show()
#' E o texto acaba aqui.
O comando para publicar o script é
pypublish -f (html ou pdf) arquivo.py
Para saída em pdf é necessário ter instalado pandoc e pdflatex.
Usando pweave
O comando pweave recebe um arquivo texto com trechos em Python e o converte para um documento processado contendo os trechos de código e seu resultado. Figuras são embutidas direto na página. O código incluido nos code chunks é executado na mesma seção (ou seja, tudo que foi escrito em um trecho continua valendo nos próximos).
% título
% author
% data
este texto é um exemplo em markdown para pweave.
<<>>=
print('hello!')
var = 7
@
O valor de var é <%= var %>!.
Abaixo um gráfico (com legenda!). O código usado para gerar o gráfico
não aparece no resultado final.
<<caption='Gráfico com legenda.',echo=False>>=
import numpy as np
import matplotlib.pyplot as plt
plt.plot(np.random.rand(10), '-')
plt.show()
@
E o texto acaba aqui.
O comando usado para processar o arquivo acima é:
pweave -f (formato incluso na lista acima) arquivo
Lembre-se de que o arquivo de entrada deverá ser compatível com o formato escolhido. Um outro exemplo pode ser este texto mesmo, que foi compilado usando Pweave. Seu código fonte pode ser visto aqui.
O resultado gerado pelos exemplos acima pode ser visto aqui. Apesar de ambos comandos gerarem a mesma saída eles tem usos diferentes. Quando desejamos fazer um texto que contém exemplos e gráficos gerados usando Python é melhor usar o comando pweave. Por outro lado, se temos um código já pronto que precisa ser usado em outros scripts e queremos documentá-lo sem alterar sua funcionalidade podemos usar o pypublish.
Espero que este texto tenha sido útil. Tenho visto o Pweave como uma excelente alternativa ao Jupyter Notebook para a criação de textos técnicos, com a grande vantagem de que posso usar meu editor de texto favorito ao invés da interface Web do Jupyter. Qualquer dúvida ou comentário é só comentar. Se gostou, compartilhe e ajude o blog a ficar mais conhecido ;)
.jpg)