Open MPI logo

Network Locality Devel Mailing List Archives

  |   Home   |   Support   |   FAQ   |   all Network Locality Devel mailing list

Subject: Re: [netloc-devel] doxygen
From: Jeff Squyres (jsquyres) (jsquyres_at_[hidden])
Date: 2014-01-14 13:37:33


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.

+1.

-- 
Jeff Squyres
jsquyres_at_[hidden]
For corporate legal information go to: http://www.cisco.com/web/about/doing_business/legal/cri/