[petsc-dev] PETSc "testing" infrastructure

[Barry Smith]

> On Jun 21, 2016, at 2:40 AM, Patrick Sanan <patrick.sanan at gmail.com> wrote:
> 
> PR #498 made.
> 
> I am also interested in making an edit of the dev manual more broadly.
> Are there any unusual restrictions on the latex build on the machine
> where the docs are generated?

   Unusual? I guess just make your changes and we'll see if anything breaks on the "official doc build machine"

  Thanks

   Barry

> 
> On Mon, Jun 20, 2016 at 6:49 PM, Barry Smith <bsmith at mcs.anl.gov> wrote:
>> 
>>  Patrick,
>> 
>>    Thanks, make it a pull request to master and I'll merge it right in.
>> 
>>  Barry
>> 
>>> On Jun 20, 2016, at 5:54 AM, Patrick Sanan <patrick.sanan at gmail.com> wrote:
>>> 
>>> 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.
>>>> 
>>> <0001-Dev-manual-add-subsection-on-expected-fields-for-man.patch>
>>