From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me X-Spam-Level: X-Spam-Status: No, score=-1.9 required=5.0 tests=BAYES_00,FREEMAIL_FROM autolearn=unavailable autolearn_force=no version=3.4.4 X-Received: by 10.182.251.230 with SMTP id zn6mr7795871obc.14.1387275105338; Tue, 17 Dec 2013 02:11:45 -0800 (PST) X-Received: by 10.182.44.198 with SMTP id g6mr3434obm.35.1387275105280; Tue, 17 Dec 2013 02:11:45 -0800 (PST) Path: border1.nntp.dca3.giganews.com!backlog3.nntp.dca3.giganews.com!border3.nntp.dca.giganews.com!border1.nntp.dca.giganews.com!border4.nntp.dca.giganews.com!border2.nntp.dca.giganews.com!nntp.giganews.com!p15no30855831qaj.0!news-out.google.com!p7ni20512qat.0!nntp.google.com!ie8no20254132qab.0!postnews.google.com!glegroupsg2000goo.googlegroups.com!not-for-mail Newsgroups: comp.lang.ada Date: Tue, 17 Dec 2013 02:11:45 -0800 (PST) In-Reply-To: Complaints-To: groups-abuse@google.com Injection-Info: glegroupsg2000goo.googlegroups.com; posting-host=155.253.16.219; posting-account=uPViEgkAAACC04vaTYL5Kyk76brV1MA_ NNTP-Posting-Host: 155.253.16.219 References: User-Agent: G2/1.0 MIME-Version: 1.0 Message-ID: Subject: Re: Documentation tools and standards? From: Maurizio Tomasi Injection-Date: Tue, 17 Dec 2013 10:11:45 +0000 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable X-Original-Bytes: 2849 Xref: number.nntp.dca.giganews.com comp.lang.ada:184284 Date: 2013-12-17T02:11:45-08:00 List-Id: On Friday, December 13, 2013 10:23:43 PM UTC+1, Diogenes wrote: > As far as the technical documentation...do you guys typically use Doxygen= ,POD,NDoc, etc..? Which one seems to work best for you? I do not like very much to interweave large chunks of documentation with th= e code, so instead of using tools like Doxygen I usually write the document= ation separately. I have used Sphinx (http://sphinx-doc.org/latest/) many times and I must sa= y I really like it. Although it is python-centered, it can work with other = languages as well. The "sphinx-contrib" package includes a number of plug-i= ns (https://bitbucket.org/birkenfeld/sphinx-contrib), and one of them ("ada= domain") adds support for Ada. To see how the documentation looks, see here (selecting "Show source" from = the menu on the left will show you the input file used to produce the docum= entation): http://docs.python.org/2/reference/index.html >From my point of view, a nice feature of Sphinx is its support for ReadTheD= ocs (https://readthedocs.org/), a site which allows to publish online your = documentation (obviously this is ok only if your project is open source or = public domain). ReadTheDocs implements its own Sphinx style, which I like m= ore than the default one. The repository is available on GitHub (https://gi= thub.com/snide/sphinx_rtd_theme). As an example of the style (and indirectl= y of the theming capability of Sphinx), here is the documentation I am writ= ing for a small C library I am developing in my spare time: http://hpixlib.readthedocs.org/en/latest/introduction.html Cheers, Maurizio.