+1 on Jeff's comments.
I think this is fine to push in. As far as format of the output HTML and
PDF are good. We can work on man pages in the next pass, but it would be
nice to put in there eventually. As far as examples, I say we just point to
some examples in either test/ or (create an) examples/. Some small inline C
code might be useful - particularly for the internal APIs, but if that
becomes difficult to support I would be fine with not doing it for now.
On Tue, Jan 14, 2014 at 12:37 PM, Jeff Squyres (jsquyres) <
> On Jan 14, 2014, at 10:48 AM, Brice Goglin <Brice.Goglin_at_[hidden]> wrote:
> > Before I push all the hwloc doxygeniry to netloc, are you guys OK with
> > everything it means?
> > * when building from GIT, it runs doxygen to build the doc
> > * when doing make dist, it runs doxygen and puts the doc in the tarball
> > (which means we may need some changes to the distrib script?)
> > * when building from tarball, it just installs the doc that was prebuilt
> > in the tarball
> > I'll remove some obsolete quirks from the code but we'll still have a
> > pretty huge doc/Makefile.am
> > (hwloc is https://github.com/open-mpi/hwloc/blob/master/doc/Makefile.am)
> I'm generally ok with it. If there's something better, I'm all for it,
> but I don't have the cycles to investigate that at the moment. :-\
> I think the most likely contender is the one I mentioned on the call the
> other day -- was is "rosetta", or something like that?
> > Questions:
> > * do we want manpages, HTML and PDF doc? I tend to prefer the HTML, but
> > manpages may still be useful to some people, and PDF is good for
> > searching keywords.
> Can we have all? I see use cases for all 3.
> That being said, if it's too difficult to do all three, I think HTML is
> the bare minimum.
> > * PDF in both A4 and letter? (letter-only is fine for me)
> If we don't need A4, then Letter-only is certainly easier. The
> generate-the-PDFs-twice stuff in hwloc is kinda a PITA.
> > * Assuming we ever have a netloc.doxy with a short introduction before
> > the actual doxygen output, will we export it to the README? I'd say no,
> > just refer to the main doc.
> Agreed. Having the README generated is kind of a PITA (I frequently have
> to git checkout README in hwloc to get rid of the generated README in my
> local tree where the only difference is the generated date at the bottom).
> > * Any idea if we'll ever embed an C example in the doc? I hope we can
> > point to example files instead.
> I don't know.
> But if we're documenting an API, I think it is useful to be able to embed
> actual code examples in the documentation. That being said, I don't care
> much if those examples are inline with the documentation or included in
> sub-files somehow.
> > * Any idea if we'll ever need support for both prebuilt and
> > runtime-built documentation images? I'd say prebuilt is enough, we don't
> > ever modify these image sources in hwloc anyway.
> Jeff Squyres
> For corporate legal information go to:
> netloc-devel mailing list
Assistant Professor of Computer Science
University of Wisconsin-La Crosse