CMake - Windows-compatible doc bootstrapping

[idigdoug]

Pretty much every Python install includes Docutils, and Docutils is 95% of what is needed to bootstrap docs on Windows. Fill in the rest.

I think this addresses issue #327

• docutils_txt.py is a Docutils text-output Writer class with support for writing a C file.
• rst2man.py is a wrapper for Docutils converting to MAN file. (Copied from Docutils repo.)
• rst2txt.py is a wrapper for Docutils converting to TXT file. (Same as rst2man.py but it uses docutils_txt as the Writer.)
• split_man.py is a Python implementation of split_man.sh.
• Change CMake build to use the new scripts.

[idigdoug]

More precisely, it fixes the CMake side of things. I don't have the autoconf stuff running in my environment right now, so I didn't mess with that.

[idigdoug]

The help.cc output is a little bit different.

• I didn't indent quite as much as the man page did.
• I put in a few additional empty lines between some things.
• This doesn't try to wrap in the middle of words.

[idigdoug]

I reverted the updated bootstraps before committing... Not sure if you wanted them included. Let me know.

[skvadrik]

@idigdoug Also please enable docs regeneration on CI (https://github.com/skvadrik/re2c/blob/master/.github/workflows/ci-cmake.yml).

[idigdoug]

• GithubActions for macOS builds currently fail as https://github.com/skvadrik/re2c/actions/runs/3305730856/jobs/5456773661#step:15:21. Python package docutils is installed (see https://github.com/skvadrik/re2c/blob/master/.github/workflows/ci-cmake.yml, step Install Python Dependencies). I'm not sure if it's related to the shebang I asked you to fix in one of the comments.

The issue is that the Python modules are being installed here:

/Users/runner/hostedtoolcache/Python/3.10.8/x64/lib/python3.10/site-packages

But the Python installation found by find_package is here:

/usr/local/Frameworks/Python.framework/Versions/3.10/bin/python3.10

[idigdoug]

@idigdoug Also please enable docs regeneration on CI (https://github.com/skvadrik/re2c/blob/master/.github/workflows/ci-cmake.yml).

I'm not sure I understand this. It's already building the -full preset, and that has RE2C_REBUILD_DOCS=true. Am I missing something?

[idigdoug]

Sorry, the review re-request was a click.

[skvadrik]

Thanks for addressing the comments! There are a few more things:

• Please squash https://github.com/skvadrik/re2c/pull/419/commits/8653f08f58d7f02b4cf1f833ba813e5cb9fdfa7d into https://github.com/skvadrik/re2c/pull/419/commits/e933043650192eae865f22c330504eff405c0933 before merging

• Also please enable docs regeneration on Windows on CI:

I'm not sure I understand this. It's already building the -full preset, and that has RE2C_REBUILD_DOCS=true. Am I missing something?

Docs regeneration is currently disabled on Windows builds on CI (see e.g. this build: https://github.com/skvadrik/re2c/actions/runs/3314965984/jobs/5476614508#step:14:17). This is disabled in cmake presets on line 262, line 282 and line 302. After you remove it, docs will be regenerated on CI builds. Also there is some special-casing in ci-cmake.yml for Windows that should probably be removed.

[skvadrik]

As for python root dir, I think issue is related: https://github.com/actions/setup-python/issues/162#issuecomment-1238566878 (it hasn't yet been fixed on macOS, which falls in line with the only failing builds being the macOS ones). Let's keep the -DPython3_ROOT_DIR workaround for now.

[skvadrik]

Tiny thing: on the first commit re2c - Windows-compatible doc bootstrapping, did you mean "CMake: Windows-compatible doc bootstrapping" ? I think it's the last one --- checks are passing.

[skvadrik]

Merged. Thanks @idigdoug !