[MIR] naturaldocs

[Raphaël Pinson]

Binary package hint: naturaldocs

The augeas package (https://launchpad.net/ubuntu/natty/+source/augeas) provides a way to document its APIs using NaturalDocs. This functionality has been activated in the latest build uploaded to Natty (0.7.4-0ubuntu1) but the naturaldocs package is in universe and augeas is in main.

This bug requests the inclusion of naturaldocs in main as a build-dependency for augeas.

The naturaldocs package meets the all the requirements for MIR:
   1. it is already in universe and builds fine for all archs (it is an arch-indep package)
   2. it is a new build dependency of a package already in main (augeas) and useful for users (shipping doc with lenses is something users would really benefit from)
  3. there is no security concerns known about this package
  4. the package is very easy to install and use, and has no known bugs
  5. the command-line tool is easy to use and comes with a manpage
  6. the only build dependency is debhelper
  7. the package complies with FHS
  8. the package is very easy to maintain
  9. the package description is complete and accurate

[Alexander Sack (asac)]

please review the current packages in main and list what other packages could get docs enabled when this enters main.

[Alexander Sack (asac)]

e.g. in general its ok; just want to use this event to review how we can most of such MIR promotion.

[Raphaël Pinson (raphink)]

I've searched a bit and found a few projects that generate their docs with NaturalDocs. Among them are maatkit, mootools and quite a few web projects. None of these are in main right now.

It is quite hard to guess which projects are using it because there is no common way of recognizing files using NaturalDocs, and these files are usually source code that might not be distributed in the debs. The only simple way is to check for projects that publish NaturalDocs-generated docs on the web, by searching for "Generated by natural docs" on a search engine.

[Raphaël Pinson (raphink)]

After further investigation, NaturalDocs is used by mostly web projects (SOAP APIs, JavaScript libraries), few of them are in Ubuntu.

Other than that, I identified a few more projects in Ubuntu which use NaturalDocs, such as skytools, xul-ext-firegpg, libsscm3, libfreebasic or libfann1. All these packages are in universe though, and while it may be interesting to write an email to ubuntu-devel to encourage the maintainers to use the naturaldocs package to generate -doc packages, it won't make this MIR more interesting for them.

That's it. I would really like to be able to activate the doc in augeas though, all the more that documentation is quite important to be able to use it efficiently.

[Alexander Sack (asac)]

MIR approved. while i would prefer to see folks reusing what already exists, its just doc gen tool that will not be shipped on images. subscribe ubuntu-archive to promote so build failures get fixed. Thanks!

[Raphaël Pinson (raphink)]

Thank you.

[Martin Pitt (pitti)]

Promoted naturaldocs to main.

[Raphaël Pinson (raphink)]

Thank you Martin.