Thadeu Lima de Souza Cascardo <[email protected]> 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 <[email protected]> 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 >> >[email protected] >> >http://lists.libreplanetbr.org/mailman/listinfo/libreceita >> >> -- >> Sent from my Android device with K-9 Mail. Please excuse my brevity. -- Gabriel Krisman Bertazi
