Open MPI logo

Network Locality Devel Mailing List Archives

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

Subject: Re: [netloc-devel] doxygen
From: Brice Goglin (Brice.Goglin_at_[hidden])
Date: 2014-01-17 12:46:53


Thanks for the replies. I push things over the week-end.

We can inline some C for sure. But hwloc also has a separate hello.c
file that gets included in the doxygen output and also gets compiled as
C and as C++. I'll remove that for now.

Brice

Le 17/01/2014 18:11, Josh Hursey a écrit :
> +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.
>
> Thanks,
> Josh
>
>
>
> On Tue, Jan 14, 2014 at 12:37 PM, Jeff Squyres (jsquyres)
> <jsquyres_at_[hidden] <mailto:jsquyres_at_[hidden]>> wrote:
>
> On Jan 14, 2014, at 10:48 AM, Brice Goglin <Brice.Goglin_at_[hidden]
> <mailto: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] <mailto:jsquyres_at_[hidden]>
> For corporate legal information go to:
> http://www.cisco.com/web/about/doing_business/legal/cri/
>
> _______________________________________________
> netloc-devel mailing list
> netloc-devel_at_[hidden] <mailto:netloc-devel_at_[hidden]>
> http://www.open-mpi.org/mailman/listinfo.cgi/netloc-devel
>
>
>
>
> --
> Joshua Hursey
> Assistant Professor of Computer Science
> University of Wisconsin-La Crosse
> http://cs.uwlax.edu/~jjhursey <http://cs.uwlax.edu/%7Ejjhursey>
>
>
> _______________________________________________
> netloc-devel mailing list
> netloc-devel_at_[hidden]
> http://www.open-mpi.org/mailman/listinfo.cgi/netloc-devel