Re: Extensions Documentation

On Oct 25, 2012, at 5:07 PM, Peter Eisentraut <peter_e@gmx.net> wrote:

> I think the emerging standard is to have a README.md (or something
> similar).  This gives enough structure and formatting options for most
> extensions.

For PGXN, I have used a README.md for a readme (briefly about the extension, how to build and install it), and a
doc/$extension.mdfile for documentation on the usage of the extension. Quite a few people put all of that into the
README,though. 

> I don't think we need anything fancy to install and access the
> documentation.  Most of the time it's on a server, in which case "less"
> would do a good job.  To me, it's more important to have the
> documentation easily accessible over the internet for reference during
> development.
>
> That said, we do have a built-in documentation infrastructure, which is
> COMMENT.  So an extension could have its documentation in its comment
> and the comments on its subordinate objects.  This may or may not
> overlap with what a README would contain, but that depends on the
> situation, I think.

I think COMMENT is a bit lightweight for detailed documentation. I often write a lot of detail, including examples,
summarizations,tutorials, etc., not just brief explanations of what each object is. 

Best,

David