Re: [lp-br-sp] [libreceita] Declara e novas interfaces amigáveis

[Thadeu Lima de Souza Cascardo]

On Sat, Jan 14, 2017 at 02:41:28PM -0200, Gabriel Krisman Bertazi wrote:
> Opa Cascardo,
> 
> Parabéns pelo post! 
> 
> Antecipando a declaração desse ano, também  peguei o declara para dar uma 
> estudada essa semana.  
> 
> Aproveitei e comecei um handbook  explicando como gerar a declaração e a 
> documentar alguns comandos. Assim que tiver algo mais apresentável te 
> encaminho o patch. Também  tenho um pequeno fix para um segfault para mandar.
> 
> Sobre a documentação, eu estava pensando em fazer inlined no código e gerar 
> com alguma ferramenta (comecei usando o formato do sphinx, que permite 
> exportar para diversos formatos, inclusive um html bastante amigável. O que  
> acha de usar sphinx?
> 
> 

Dê uma olhada no comando help e nos arquivos no diretório help/. A idéia
era usar textos em um formato bem "plano" mesmo. Sem dúvida, uma
documentação com hipertexto é bem-vinda, mas o usuário de DEC VT-100
deve ser coberto também.  :-P

Sobre o sphinx, sempre associei à reStructuredText, readthedocs e
github. Na guerra de formatos, eu uso mais Markdown, ainda preciso
encontrar mais módulos que lidem com rst. Li agora mais sobre o
readthedocs e não é uma iniciativa do github, pelo contrário, é mantido
por uma comunidade e integra com outros repositórios. É só que muitos
documentos apresentam um link para "edite no github".

Me preocupa a infra-estrutura necessária para gerar os documentos. Se
puder tornar opcional a geração dos documentos, melhor. Não gostaria de
nenhuma nova dependência em runtime pra interface de texto, incluindo o
help. O desafio aqui seria não duplicar documentação por causa de
múltiplos formatos e ainda ter disponível a documentação em texto pro
comando help.

Tem alguma sugestão nesse caso? Mostramos em rst mesmo pro usuário?

Cascardo.

> 
> On January 14, 2017 2:09:25 PM GMT-02:00, Thadeu Lima de Souza Cascardo 
> <address@hidden> wrote:
> >Descrevi rapidamente num post no meu blog [1] sobre o declara e
> >mudanças
> >recentes para torná-lo mais amigável.
> >
> >Contribuições à documentação são bem-vindas, bem como contribuições de
> >código.
> >
> >Abraços.
> >Cascardo.
> >
> >[1] https://cascardo.eti.br/blog/Declara/
> >
> >
> >------------------------------------------------------------------------
> >
> >_______________________________________________
> >libreceita mailing list
> >address@hidden
> >http://lists.libreplanetbr.org/mailman/listinfo/libreceita
> 
> -- 
> Sent from my Android device with K-9 Mail. Please excuse my brevity.

signature.asc
Description: PGP signature