Thread: Extensions Documentation
Hackers, Any plans to implement a documentation standard for extensions? I would love to see `make install` create the necessary manpages and perhaps even HTML (with a link added in the proper place). Anyone given this any thought? Dim? Thanks, David
On 25 October 2012 19:31, David E. Wheeler <david@justatheory.com> wrote: > Hackers, > > Any plans to implement a documentation standard for extensions? I would love to see `make install` create the necessaryman pages and perhaps even HTML (with a link added in the proper place). Anyone given this any thought? Dim? Isn't that distro-dependent? Any proposal yourself? -- Simon Riggs http://www.2ndQuadrant.com/PostgreSQL Development, 24x7 Support, Training & Services
On Oct 25, 2012, at 10:42 AM, Simon Riggs <simon@2ndQuadrant.com> wrote: >> Any plans to implement a documentation standard for extensions? I would love to see `make install` create the necessaryman pages and perhaps even HTML (with a link added in the proper place). Anyone given this any thought? Dim? > > Isn't that distro-dependent? No. PostgreSQL ships its own documentation as man pages and HTML (or build them, I guess). Distros put them where they want,I guess, but that’s just moving files around. I'm thinking thre could be some sort of support in core for generatingdocs and adding them to wherever the core docs are (or closely related, e.g., a subdirectory). I'm thinking of Pod as the precedent here, but I think most of the popular programming language ecosystems offer somethinglike this (JavaDoc, rdoc, etc.). > Any proposal yourself? I like MultiMarkdown. There is a decent C implementation. Not sure if the project would want to use such a thing. https://github.com/fletcher/peg-multimarkdown Probably too heavy-weight. Another option is to adopt something like libsoldout (née libupskirt, http://fossil.instinctive.eu/libsoldout/)or one of its forks, e.g., sundown (https://github.com/vmg/sundown). But I am not so attached to any one solution (except SGML, pretty sure no one wants that to be part of the pg distribution,and is hateful to edit, anyway). I'd just like something, so I can tell users to just `man $extension` afterinstalling. Best, David
On Thu, 2012-10-25 at 10:31 -0700, David E. Wheeler wrote: > Any plans to implement a documentation standard for extensions? I would love to see `make install` create the necessaryman pages and perhaps even HTML (with a link added in the proper place). Anyone given this any thought? Dim? I think the emerging standard is to have a README.md (or something similar). This gives enough structure and formatting options for most extensions. 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.
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
On 10/25/12 1:53 PM, David E. Wheeler wrote: > I'm thinking of Pod as the precedent here, but I think most of the popular programming language ecosystems offer somethinglike this (JavaDoc, rdoc, etc.). The advantage that these programming language ecosystems have is that they can implement the processors for the documentation format in the language itself, so it's easy to recommend or enforce a particular system. I don't think we're going to implement any documentation processing in SQL, so we'd end up adding some kind of external dependency, and that's usually tricky. Also, there are wildly diverging paradigms in use. For example, in Perl, the convention is one man page per module. In Python, for most modules you don't get any locally installed documentation by default. Instead, you're encouraged to upload your stuff to readthedocs.org. All of these have their advantages, but I think it's too early to tell what the best convention for a PostgreSQL extension would be.
On Oct 26, 2012, at 5:27 AM, Peter Eisentraut <peter_e@gmx.net> wrote: > > The advantage that these programming language ecosystems have is that > they can implement the processors for the documentation format in the > language itself, so it's easy to recommend or enforce a particular > system. I don't think we're going to implement any documentation > processing in SQL, so we'd end up adding some kind of external > dependency, and that's usually tricky. True, which is why I was thinking of something relatively light-weight and self-contained like sundown. > Also, there are wildly diverging paradigms in use. For example, in > Perl, the convention is one man page per module. In Python, for most > modules you don't get any locally installed documentation by default. > Instead, you're encouraged to upload your stuff to readthedocs.org. All > of these have their advantages, but I think it's too early to tell what > the best convention for a PostgreSQL extension would be. Well, only because nothing much exists yet. The convention for what gets turned into proper documentation (e.g., man pagesand/or HTML output) will be whatever someone decides to implement and get committed. Because otherwise, there is noconvention at all, aside from the current convention is a plain text file stuck in the docs folder, which isn't reallydocumentation, IMHO. Best, David
On Fri, 2012-10-26 at 09:09 -0700, David E. Wheeler wrote: > On Oct 26, 2012, at 5:27 AM, Peter Eisentraut <peter_e@gmx.net> wrote: > > The advantage that these programming language ecosystems have is that > > they can implement the processors for the documentation format in the > > language itself, so it's easy to recommend or enforce a particular > > system. I don't think we're going to implement any documentation > > processing in SQL, so we'd end up adding some kind of external > > dependency, and that's usually tricky. > > True, which is why I was thinking of something relatively light-weight > and self-contained like sundown. That's a markdown library, which transforms markdown to HTML, right? So what would we do with the HTML? > > Also, there are wildly diverging paradigms in use. For example, in > > Perl, the convention is one man page per module. In Python, for most > > modules you don't get any locally installed documentation by default. > > Instead, you're encouraged to upload your stuff to readthedocs.org. All > > of these have their advantages, but I think it's too early to tell what > > the best convention for a PostgreSQL extension would be. > > Well, only because nothing much exists yet. The convention for what > gets turned into proper documentation (e.g., man pages and/or HTML > output) will be whatever someone decides to implement and get > committed. Because otherwise, there is no convention at all, aside > from the current convention is a plain text file stuck in the docs > folder, which isn't really documentation, IMHO. I don't agree with this approach. There is no need to be prescriptive. Enforcing a documentation format won't make better, or any, documentation anyway. That said, if there are things we could put in, e.g., pgxs, to make building documentation simpler, we can discuss that.
On Oct 30, 2012, at 2:08 PM, Peter Eisentraut <peter_e@gmx.net> wrote: >> True, which is why I was thinking of something relatively light-weight >> and self-contained like sundown. > > That's a markdown library, which transforms markdown to HTML, right? So > what would we do with the HTML? Put it into the HTML directory (share/docs/html/extensions/$extension.html) and inject its name into the TOC. I'd also be in favor of adding hooks to generate man pages. > I don't agree with this approach. There is no need to be prescriptive. > Enforcing a documentation format won't make better, or any, > documentation anyway. My point isn't to be prescriptive, but that actual code tends to win out in the end, as opposed to discussion. (Which, yes,I have started.) > That said, if there are things we could put in, e.g., pgxs, to make > building documentation simpler, we can discuss that. Yeah, that would be ideal. But if no one has really thought about how to go about it yet… David
"David E. Wheeler" <david@justatheory.com> writes: > Put it into the HTML directory > (share/docs/html/extensions/$extension.html) and inject its name into > the TOC. > > I'd also be in favor of adding hooks to generate man pages. Who still use their local copy of the docs (without search ability) anyway? About man pages, I don't know how many DBA are looking there when they want to find some documentation. I think it all gets down to having a local text file installed and a proper web site to show off the extension's documentation, tutorial, quick start, etc. A good example of that would be the pgmp extension: http://pgmp.projects.pgfoundry.org/ https://github.com/dvarrazzo/pgmp/ >> That said, if there are things we could put in, e.g., pgxs, to make >> building documentation simpler, we can discuss that. > > Yeah, that would be ideal. But if no one has really thought about how > to go about it yet… Well I'm not really seeing how improving the local copy of any documentation is going to change the habit of people to just use some online reference with good integrated search facility, or even more often, $SEARCH_ENGINE. Regards, -- Dimitri Fontaine http://2ndQuadrant.fr PostgreSQL : Expertise, Formation et Support
On Nov 2, 2012, at 7:56 AM, Dimitri Fontaine <dimitri@2ndQuadrant.fr> wrote: >> I'd also be in favor of adding hooks to generate man pages. > > Who still use their local copy of the docs (without search ability) > anyway? About man pages, I don't know how many DBA are looking there > when they want to find some documentation. I use man pages *all the time*. > I think it all gets down to having a local text file installed and a > proper web site to show off the extension's documentation, tutorial, > quick start, etc. A good example of that would be the pgmp extension: > > http://pgmp.projects.pgfoundry.org/ > https://github.com/dvarrazzo/pgmp/ Yes, and also http://pgxn.org/dist/pgmp/. But that doesn't help if you're offline or behind a moronic corporate firewall. > Well I'm not really seeing how improving the local copy of any > documentation is going to change the habit of people to just use some > online reference with good integrated search facility, or even more > often, $SEARCH_ENGINE. Yes, that was one of my motivations for creating PGXN. But I still would love to be able to send someone instructions likethis: pgxn install pgtap man pgtap Rather than this: pgxn install pgtap less `pg_config --docdir `/extension/pgtap.mmd The man page will be easier on the eyes, too. When I *do* need the HTML docs, I use this when I need to access the full docs on a long flight: open `pg_config --docdir`/html/index.html I would love to see an index of links to pages for each installed extension, too. We have that for contrib stuff, why notthird-party extensions? Best, David