On Fri, Jun 17, 2016 at 12:18 AM, Barry Smith <[email protected]> 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. > > > >
