2022.06.01 17:10 "[Tiff] Conversion of HTML documentation to Sphinx ReStructuredText (RST)", by Roger
I mentioned some years ago that it would be nice if we could convert the HTML documentation to a more maintainable format, and created an issue for it here: https://gitlab.com/libtiff/libtiff/-/issues/361.
Over the last few days, I've had some free time to do some work on LibTIFF and I did a preliminary conversion of the static HTML pages (not the manual pages at this point). The main manual is converted; I'm currently going back through the release notes from v4.4.0 to v4.0.9 so far.
I haven't made any material changes to the documentation other than fixing a few minor typos. It's focused upon switching the markup from HTML to RST, with any actual reorganisation or changes left for a followup MR.
To try this out:
- Check out the "rst-docs" branch
- Make sure that you have Python3 with the Sphinx package installed (you need "sphinx-build")
- Configure with CMake as usual [autotools support not yet added, but will be before submitting]
- Build the "doc-html" target.
- Documentation is in "doc/*.rst"
- Browse to "doc/html/index.html" with a web browser
I've not done any customisation of the theming or anything at this point, so the appearance is just the default Sphinx theme. I've added a few "extlinks" (see "doc/conf.py.in") to make shortcuts to bug tickets. If anyone wants to give this a look over, feedback would be welcome. If anyone wants to help out, the branch can be pushed to by anyone with GitLab access. The release notes are a bit tedious, so it's taking a while to plough through them all. But they look quite nice.
You'll see a few Sphinx warnings about bad cross-references due to the documentation not being complete at this point. And some of the markup might not be optimal until we have all of the manual pages converted and have manpage generation properly in place, but what's here seems like a good starting point, so thought now would be a good time to show it to a wider audience.