[petsc-dev] Documentation comment support

[Jed Brown]

On Tue, Jan 8, 2013 at 9:54 AM, Karl Rupp <rupp at mcs.anl.gov> wrote:

> Hi,
>
> I haven't yet thought about the system proposed by Jed below. The reason
> for this mail is that interestingly the Eigen guys have just started a
> similar discussion a couple of days ago driven by the new capabilities of
> doxygen:
>
> http://listengine.tuxfamily.**org/lists.tuxfamily.org/eigen/**
> 2013/01/msg00001.html<http://listengine.tuxfamily.org/lists.tuxfamily.org/eigen/2013/01/msg00001.html>
>
> A brief summary:
> Out of five proposals, they prefer two variants, both being a big user and
> a big reference manual accessible via a common navigation tree:
>  - Not tightly coupled. Includes cross references:
>  http://eigen.tuxfamily.org/**doc_test/4/<http://eigen.tuxfamily.org/doc_test/4/>
>
>  - A slightly modified variant of the above with a different structure:
>  http://eigen.tuxfamily.org/**doc_test/5/<http://eigen.tuxfamily.org/doc_test/5/>
> They will stick with this variant in the future.
>
> Note the small 'search' field on the top right for both variants.
>

They should make that box 10x bigger. ;-)

Those cross-references still look one-way. Is there a way to make a two-way
link, so that anywhere I mention X, the man page for X includes a link the
other way?


> If I'm not mistaken, Eigen always preferred HTML manuals (user and
> reference) over a PDF version. With the issues of linking into PDFs showing
> up repeatedly, having everything in one place seems to be the better bet.
> It doesn't need to be Doxygen, though.
>

What are the alternatives? Doxygen seems to be much more popular than any
alternative for API documentation (man pages). For HTML manuals, there is
doxygen (best integration with API docs), Sphinx (popular, but only well
integrated with Python), wikis (no a priori integration, but maybe
hackable), and LaTeX (one-way integration in PETSc by our preprocessing).



> Best regards,
> Karli
>
>
>
>
> On 12/25/2012 01:49 AM, Jed Brown wrote:
>
>> Here's a possible system that might be attainable. I probably won't
>> implement in the near future. Maybe I'll get lucky and the wiki authors
>> will fix the quirks. ;-)
>>
>> Basic idea is to have man pages generated from source code roughly as
>> now, but "user's manual" stored as a wiki. The wiki source can be in the
>> repository for convenient batch editing. Here are a couple example pages
>> from a nicely-done project wiki that you can clone (git clone
>> https://github.com/snowplow/**snowplow.wiki<https://github.com/snowplow/snowplow.wiki>
>> ):
>>
>> https://github.com/snowplow/**snowplow/wiki/Technical-**architecture<https://github.com/snowplow/snowplow/wiki/Technical-architecture>
>> https://github.com/snowplow/**snowplow/wiki/SnowPlow-setup-**guide<https://github.com/snowplow/snowplow/wiki/SnowPlow-setup-guide>
>>
>> This wiki system (named "gollum") is nice because it supports many
>> markup dialects, stores all its data in a normal repository, supports
>> mathjax, is open source (MIT license), and is hackable.
>>
>> Exporting as an attractive PDF is possible with MediaWiki (e.g.,
>> download the PDF for http://en.wikibooks.org/wiki/**LaTeX<http://en.wikibooks.org/wiki/LaTeX>),
>> but MediaWiki
>> isn't backed by a versioned repository so you can't edit it offline.
>> Gollum claims that it would be easy to write a PDF exporter as a plugin;
>> I don't know if anyone has yet.
>>
>> Now we want cross-references between source documentation and wiki. The
>> forward direction can be implemented as an input filter (e.g.,
>> translating "[[Manual Section]]" appearing in source man pages to use
>> the link keyword). Probably the nicest way to do the reverse would be to
>> dynamically translate "wiki" URLs to display man pages. I'd have to look
>> more closely to see if that would be implementable using a plugin or if
>> it would need to modify the base system. Best would be to teach the wiki
>> about doxygen-style autolinks (similar to PETSc, SomeFunction(),
>> #ENUM_VALUE, ::SomeTypedef) so that natural text would produce those
>> links.
>>
>> Finally, doxygen can do references with \cite{} and BibTeX. MediaWiki
>> also has a BibTeX extension
>> (http://www.mediawiki.org/**wiki/Extension:Bibtex<http://www.mediawiki.org/wiki/Extension:Bibtex>
>> ).
>>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20130108/f2620ab0/attachment.html>