[haiku] Re: Documenting your package
- From: "Charlie Clark" <charlie@xxxxxxxxxxxxxx>
- To: haiku@xxxxxxxxxxxxx
- Date: Tue, 05 Apr 2016 11:01:00 +0200
Am .04.2016, 10:51 Uhr, schrieb Luposian <luposian@xxxxxxx>:
Can't we just translate all documentation to a standard format, like
plain ASCII or HTML or PDF or a cross-platform format that anyone can
read without terminal commands or such? Why continue to do things in
such an archaic CLI fashion, in 2016, concerning, of all things,
documentation?
man pages pretty much are just plain ASCII. HTML, and especially PDF, are
much more difficult to do.
FWIW, in the Python world we use Sphinx
[
http://www.sphinx-doc.org/en/stable/] to handle documentation generation.
Docs themselves are written in ReST or Markdown, which are easy enough to
use with sufficient practice, and Sphinx handles the generation of the
desired output format. This has been shown to reduce the hurdle for
writing docs somewhat but the biggest problem remains that developers
generally don't like writing docs.
Charlie
--
Charlie Clark
Kronenstr. 27a
Düsseldorf
D- 40217
Tel: +49-211-938-5360
Mobile: +49-178-782-6226
Other related posts:
