[petsc-dev] PETSc "testing" infrastructure

[Patrick Sanan]

Cool - a patch from master is attached which adds a section to the dev
manual, and updates the link to the Sowing docs.

I added the "Concepts" and "Keywords" sections to the list, but I'm
not sure if those are currently used in the docs.

Also on a branch here:
https://bitbucket.org/psanan/petsc/branch/psanan/doc-manpage-format

On Sat, Jun 18, 2016 at 3:52 AM, Barry Smith <bsmith at mcs.anl.gov> wrote:
>
>    Patrick,
>
>    Looks pretty complete to me.
>
>    Thanks
>
>    Barry
>
>> On Jun 17, 2016, at 8:23 AM, Patrick Sanan <patrick.sanan at gmail.com> wrote:
>>
>> On Fri, Jun 17, 2016 at 12:18 AM, Barry Smith <bsmith at mcs.anl.gov> wrote:
>>>
>>>   There is a lot going on currently to enhance the PETSc "testing" infrastructure; in particular Lisandro has begun to set up stuff on both github and bitbucket.
>>>
>>>   I've update the PETSc "Dashboard" for testing at ftp://ftp.mcs.anl.gov/pub/petsc/nightlylogs/index.html with more links and a bit more context so people can understand it better. I would like links to other high-level packages testing dashboards such as SLEPc so if you know any send them to me.
>>>
>>>   Here "testing" does not just mean running the test suite but also means collecting gcov information, running static analyzers on the code, running with valgrind, controlling symbol visibility and anything else you can think of that helps detect bugs and flaws in the software. For example tools that automatically check that all visible symbols had manual pages and reported problems, manual pages were complete, etc would be good additions. Currently we rely to much on the kindness of strangers who report bugs in our documentation.
>>>
>>>   Comments, input?
>> Re the man pages, here's a draft checklist of things that should be
>> there - what's missing? An idea (which I'm happy to implement) is to
>> add a section to the dev manual stating what is required and
>> recommended to be on each man page. Having that codified would be a
>> first step to (semi-)automated maintenance.
>>
>> Standard Data
>>
>> - Function name
>> - Brief summary
>> - "Collectivity"
>> - Input and Output parameters (if any)
>> - Level
>> - Keywords
>> - See Also (and if appropriate, symmetrize so that linked pages point back)
>>
>> Additional Data, if appropriate
>>
>> - Longer description
>> - If there are any relevant output parameters, is the user responsible
>> for freeing (or not freeing) something?
>> - References to manual or other docs
>> - References to literature
>> - Fortran-specific information
>> - Options Database Keys
>>
>> Check formatting and links
>>
>> - Sowing formatting correct (see Dev manual for different special
>> comment syntax)?
>> - Synopsis and signature correct?
>> - Covered by a tutorial example (in .../examples/tutorials/)?
>> - Text grammatically correct?
>> - Automatic links to other man pages, source, etc. in place correctly?
>>
>>
>>>
>>>   Barry
>>>
>>> Currently this file is under RCS on the MCS filesystem, if others would like to contribute to it I'll put it under git at bitbucket.
>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: 0001-Dev-manual-add-subsection-on-expected-fields-for-man.patch
Type: application/octet-stream
Size: 4183 bytes
Desc: not available
URL: <http://lists.mcs.anl.gov/pipermail/petsc-dev/attachments/20160620/00722c7e/attachment.obj>