On Tue, 2008-11-04 at 18:13 +0100, David Schmitt wrote: > Brice Figureau schrieb: > > On Tue, 2008-11-04 at 10:04 -0600, Luke Kanies wrote: > >> On Nov 4, 2008, at 9:28 AM, Brice Figureau wrote: > >>> On Tue, 2008-11-04 at 09:05 -0600, Luke Kanies wrote: > >>>> > >>>> > >>>> I'd do that. Just generate docs for what people specify. > >>>> > >>>> I'd also probably have puppetdoc accept standard ARGV arguments, and > >>>> consider those to be normal manifests, which it could then produce > >>>> output for on stdout. E.g., you could do: > >>>> > >>>> puppetdoc manifests/site.pp > >>>> > >>>> and it would give you docs for just that file, > >>> Yes, that is planned, but that's a complete different thing than the > >>> current rdoc implementation (although it is simple to have). > >>> What is still unknown at this stage for this mode is what to output in > >>> this mode... All comments? Only classes, defines and nodes ? in which > >>> order (I'm afraid that's not something I can control though) ? > >> I'd do whatever you'd normally show. > >> > >>>> or, as you say, you > >>>> could do: > >>>> > >>>> puppetdoc --modulepath <...> --manifest <...> > >>>> > >>>> Maybe the --manifest becomes redundant at that point, though. > >>> My idea was: > >>> puppetdoc --modulepath <module path1> --modulepath <module path2> > >>> <path1> <path2>... > >>> > >>> path1: contains manifests > >>> path2: contains manifests too > >>> modulepath1: contains only a module hierarchy > >>> modulepath2: contains only a module hierarchy > >>> > >>> If path1 or path2 encompass any module specified in modulepath, those > >>> get treated as module of course. The question that remains is, if > >>> path1 > >>> and path2 don't encompass any module path, should I treat those module > >>> path as information, or should I go and scan also those to produce > >>> documentation. > >> > >> I'm not sure I understand the complication; module paths contain > >> modules, non-module paths contain normal manifests, right? > > > > Right, of course :-) > > > > My problem is: > > Let's say I have: > > > > /etc/puppet/modules/module1 > > /etc/puppet/modules/module2 > > > > and some global manifests > > /etc/puppet/manifests/site.pp > > ... > > > > and some other global manifests > > /tmp/manifests/site.pp > > > > > > If I run: > > puppetdoc /etc/puppet > > > > It will scan both the modules and the global manifests, but have no way > > to understand that module1 and module2 are modules. > > puppetdoc should use the same code as other puppet* binaries to read and > interpret puppet.conf and commandline parameters and it should use the > modulepath and friends from there. They contain (by definition) all > necessary information and all site-local peculiarities. > > That should generalise properly to create standalone module > documentation with > > puppetdoc --manifest /dev/null --modulepath /path/to/modules/
That might be the best solution. I wasn't keen about using puppet.conf for puppetdoc (it wasn't using it before my patch), as it would tie documentation generation to a specific installation. And there is the problem of environments, too. But, since you can override puppet.conf directives with the command line arguments, I think that will works. OK, to summarize: By default puppetdoc uses the default puppet.conf, except if overriden with --configdir or --config (default puppet* behavior). If --modulepath or --manifests are provided, they override puppet.conf defaults. Now, the behavior is to generate documentation for both site manifests _and_ modulepath (if not empty). If modulepath is overriden and defaults to /dev/null or an inexistant path, don't produce doc for modules. Same for manifests. If --mode is rdoc and path are passed in ARGV, then the additionnal path are scanned for global manifests. If those path overlaps with any configured modulepaths, then we exit with an error. If --mode is not rdoc and filenames are passed in ARGV, then perform a straight documentation extract (no fancy formatting and so) on stdout. Luke, do you agree with this? Did I forgot anything? If not then I'll follow this specs. -- Brice Figureau <[EMAIL PROTECTED]> --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Puppet Developers" group. To post to this group, send email to puppet-dev@googlegroups.com To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/puppet-dev?hl=en -~----------~----~----~----~------~----~------~--~---
