[petsc-dev] User(s) manual sections field in manual pages?

[Jed Brown]

Scott Kruger <kruger at txcorp.com> writes:

>>> So many projects use it (including the linux kernel, moving away from
>>> bookdown, says wikipedia)
>> 
>> They switched from Docbook to rst.
>> 
>>    https://www.kernel.org/doc/html/latest/
>
> Is that the default C autodoc extension, or hawkmoth?
>
> https://hawkmoth.readthedocs.io/en/latest/extension.html

There is no reference to hawkmoth in the repository.  At a glance, it
looks like Hawkmoth exists to process rst comments.  The Linux kernel
uses a custom javadoc-like syntax (for historical reasons) for man
pages.  Manually converting our comments is a non-starter so there's no
getting around writing a Sowing parser in order to use Sphinx.  With
such a parser written, we could make it "run once" to replace all the
comments with a new format or (my plan) we could just keep our
Sowing-style comments.

>> 
>> Sphinx supports a search dialog, but it would be a lot nicer if it would
>> autocomplete.
>
> https://pypi.org/project/sphinxcontrib-lunrsearch/

Low-traffic project, but the demo looks good.