Documentation tools and standards?

Documentation tools and standards?

[Diogenes]

I'm at the point where I really should be doing a formal Requirements, Architecture/DDD, and Technical Docs.

As far as the Requirements and Arch docs, are there any published standards and tools that the Ada community generally prefers when working with Ada code? Any links to those standards?

As far as the technical documentation...do you guys typically use Doxygen,POD,NDoc, etc..? Which one seems to work best for you?

Tips and pointers are appreciated.

Diogenes

Re: Documentation tools and standards?

[erlo]

On 12/13/2013 10:23 PM, Diogenes wrote:
> I'm at the point where I really should be doing a formal Requirements, Architecture/DDD, and Technical Docs.
> 
> As far as the Requirements and Arch docs, are there any published standards and tools that the Ada community generally prefers when working with Ada code? Any links to those standards?
> 
> As far as the technical documentation...do you guys typically use Doxygen,POD,NDoc, etc..? Which one seems to work best for you?
> 
> Tips and pointers are appreciated.
> 
> Diogenes
> 

I don't think that Doxygen supports Ada, but there is a tool called
AdaDoc that will. You can find it on sourceforge
http://adadoc.sourceforge.net/


Erlo

Re: Documentation tools and standards?

[erlo]

On 12/13/2013 11:37 PM, erlo wrote:
> On 12/13/2013 10:23 PM, Diogenes wrote:
>> I'm at the point where I really should be doing a formal Requirements, Architecture/DDD, and Technical Docs.
>>
>> As far as the Requirements and Arch docs, are there any published standards and tools that the Ada community generally prefers when working with Ada code? Any links to those standards?
>>
>> As far as the technical documentation...do you guys typically use Doxygen,POD,NDoc, etc..? Which one seems to work best for you?
>>
>> Tips and pointers are appreciated.
>>
>> Diogenes
>>
> 

Found this site:
http://giellatekno.uit.no/doc/infra/infraremake/DocumentationGenerators.html

Erlo

Re: Documentation tools and standards?

[Georg Bauhaus]

On 13.12.13 22:23, 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?

For software that is distributed with at least Ada spec files,
a good IDE that facilitates source code navigation is helpful.
Description of associated declarations need not be separated
from bodies (like with POD etc), as there aren't any.

Granted, this solution isn't integrated with the additional requirements
of traditional technical press management, where applicable.

There's also AdaBrowse, http://home.datacomm.ch/t_wolf/tw/ada95/adabrowse/

Re: Documentation tools and standards?

[Simon Wright]

Diogenes <phathax0r@gmail.com> writes:

> As far as the Requirements and Arch docs, are there any published
> standards and tools that the Ada community generally prefers when
> working with Ada code? Any links to those standards?

Some UK MoD contractors still work to MIL STD 498[1], or at least the
DIDs (which specify the required contents of each document type). The
problem with IEEE 12207 is that it's a lot less prescriptive than 498,
and, the last time I checked, it wasn't freely available (but see [2];
not sure of the legality of this).

[1] http://pushface.org/mil_498.html 
[2] http://www.math.unipd.it/~tullio/IS-1/2009/Approfondimenti/ISO_12207-2008.pdf

Re: Documentation tools and standards?

[Jacob Sparre Andersen]

Diogenes <phathax0r@gmail.com> writes:

> As far as the technical documentation...do you guys typically use
> Doxygen,POD,NDoc, etc..? Which one seems to work best for you?

I use LaTeX for technical documentation.  On projects with
non-LaTeX-literate participants I use some kind of Wiki.

Greetings,

Jacob
-- 
"It's not a question of whose habitat it is,
 it's a question of how fast you hit it."

Re: Documentation tools and standards?

[Mike H]

In message <d427d12b-732c-4e44-a704-c31498886253@googlegroups.com>, 
Diogenes <phathax0r@gmail.com> writes
>As far as the Requirements and Arch docs, are there any published 
>standards and tools that the Ada community generally prefers when 
>working with Ada code? Any links to those standards?
>
Even though there was an element of overkill for the size project I was 
associated with (replacing line-side copper wire with virtual copper 
wire) I found European Standard EN 50128 to be a useful template.

-- 
The thing I like best about the Internet is that no one
knows that, in reality, I am just another old dog!
Mike

Re: Documentation tools and standards?

[Maurizio Tomasi]

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 the code, so instead of using tools like Doxygen I usually write the documentation separately.

I have used Sphinx (http://sphinx-doc.org/latest/) many times and I must say 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-ins (https://bitbucket.org/birkenfeld/sphinx-contrib), and one of them ("adadomain") 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 documentation):

http://docs.python.org/2/reference/index.html

From my point of view, a nice feature of Sphinx is its support for ReadTheDocs (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 more than the default one. The repository is available on GitHub (https://github.com/snide/sphinx_rtd_theme). As an example of the style (and indirectly of the theming capability of Sphinx), here is the documentation I am writing for a small C library I am developing in my spare time:

http://hpixlib.readthedocs.org/en/latest/introduction.html


Cheers,
  Maurizio.