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

[Gabriel Krisman Bertazi]

Thadeu Lima de Souza Cascardo <address@hidden> writes:

> 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?

Seria algo como um "make [html|pdf|rst]docs" separado, você não precisa
necessariamente gerar a documentação como parte do processo de build.
Até onde sei, o sphinx só precisa de dependências em runtime quando
exportar html com um tema custom.

No caso mais simples, seria possível mostrar em rst mesmo, que é uma
opção da ferramenta.  Sei que é possível exportar comentários inlined no
código, mas integrar com um parametro --help me parece um caso um pouco
mais complicado (i.e. kernel-doc?), e não tenho a resposta agora,
preciso olhar como ficaria.

Abraço



>
> 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.

-- 
Gabriel Krisman Bertazi