[erlang-questions] Documenting Erlang project(s)

[Nick Gerakines]

Subject: Documenting Erlang project(s)

I'm getting ready to hand of an erlang project to another engineer and
*shame on me* my documentation isn't as organized as I'd like it to
be. I've been writing a lot lately about the different parts,
components, modules and configurations and now its time to organize it
all.

My documentation goals cover several areas:
 - A user guide that explains what the service does and how it operates
 - Module documentation
 - An overview of the module documentation
 - Configuration documentation
 - Build, package and deployment documentation

I've read extensively on both edoc and docbuilder and I've tried
generating documentation with both of them. The issue is that both
have quirks and I'm not really getting what I want out of them.

This is what I've gone through to get where I am:

Attempt 1: edoc

I've used edoc to build html documentation from Erlang modules and an
overview, but I can't for the life of me figure out how to create
something like the a user guide. It also seems to not allow me to
create individual documents for configuration files and build
instructions.

Good: module docs, overview docs, really pretty, clean xhtml, code and
docs are right next to each other
Bad: config docs, build/deploy docs, user guide

Attempt 2: docbuilder docb_gen + docb_transform

This route lets me go a little farther with generating docbuilder xml
from module documentation, but that seems like its about it. With that
I can at least create separate xml files for the other components.

Good: module docs, overview docs, config docs, build/deploy docs, user guide
Bad: Managing multiple files, sort of a pain in the ass

Attempt 3: docbuilder manual xml + docb_transform

This is the last step although its not ideal. Instead of generating
all of my documentation from .erl or .edoc files, I only create .xml
files that are fed into docb_transform.

Good: Documentation coverage for everything.
Bad: Documentation is completely separate from actual code, not xhtml,
no easy way to do things like macros and change notes/warnings.

So, down to my question: I really like edoc and the way I can document
my modules and generate (pretty) documentation from it. I don't like
the way it doesn't seem to be able to do as much as docbuilder. Is
there a way that I can have the best of both worlds? Is there a way to
have all of my documentation from inline .erl or .edoc files without
having to manage 10+ xml files?

Related: How are the docs on erlang.org/doc built? Is there a special
version of docbuilder used?

# Nick Gerakines