Stop attempting to convert previously-converted doc headers

[reuk]

Updates the documentation conversion script so that it doesn't try to convert file headers which have already been converted. This should mean that, after the initial run, subsequent runs of the do_doc_convert script do not make any changes to the codebase, which should make rebases from pre-Doxygen code much easier.

[thk123]

Looks good though I think one line is little confusing - will try it out anyway and report back.

[thk123]

Unless I am misunderstanding something, can we not use converted here. Why do we now need the check converted is truthy? Surely if it is an empty string this amounts to returning block_contents.group(0)?

[reuk]

Well spotted, I'll fix that now.

[reuk]

Should be fixed now.

[thk123]

LGTM - but I will test it

[thk123]

LGTM - but I will test it works for my use case.

[thk123]

It works - the approach that works for me is to do a rebase on the current base (i.e not master) first. I will document this on the wiki and share on slack.

[thk123]

When this is merged this documentation can be simplified to just say "grab latest version of the script": https://github.com/diffblue/doc-diffblue-common/wiki/Rebasing-PRs-after-the-Doxygen-Change

[martin-cs]

When I try to run the script as a stand-alone program (to do help update a branch) it seems to hang:

$ reformat_docs.py --help 
^C/tmp/reformat_docs.py: line 3: syntax error near unexpected token `('
/tmp/reformat_docs.py: line 3: `Field = collections.namedtuple('Field', ['name', 'contents'])'

$ reformat_docs.py analyses/constant_propagator.h
^C/tmp/reformat_docs.py: line 3: syntax error near unexpected token `('
/tmp/reformat_docs.py: line 3: `Field = collections.namedtuple('Field', ['name', 'contents'])'

[reuk]

Interesting - this suggests that it doesn't like namedtuple for some reason, but that's been in Python since v2.4. Can you open an interpreter and run

import collections
Field = collections.namedtuple('Field', ['name', 'contents'])

[reuk]

Ignore what I said above. The script is not designed to be run directly (which is why it was not marked executable). If you want to run it in that way, you should add #!/usr/bin/env python as the first line of the file, or alternatively run it using python reformat_docs.py.

[reuk]

I updated the wiki page with a bit more info about actually running the conversion scripts.

[martin-cs]

On Thu, 2017-06-15 at 07:41 -0700, Reuben Thomas wrote: I updated the wiki page with a bit more info about actually running the conversion scripts.

Appreciated. We should really send out a version of this on cprover-announce and / or cprover-support as this will break a lot of external folk's code.