Hi folks,
To follow up to my message from last week. I have completed the initial bulk conversion and there is now a MR open for this here: https://gitlab.com/libtiff/libtiff/-/merge_requests/349 This needs two prerequisites to build: (1) python sphinx and (2) sphinx_rtd_theme. The CI has been updated to build this, and if you install them yourself you can build locally with either CMake or Autotools. You can also see a staged copy of the documentation here: http://rleigh.gitlab.io/libtiff/ (content will replace http://libtiff.gitlab.io/libtiff/ once merged). As mentioned before, this is just the initial conversion with minor changes only. It still needs a thorough read to pick out any lingering HTML tags or inconsistent formatting which wasn't picked up on the initial passes. It provides links to the HTML manual pages, but no deeper integration than page links at this point (no cross-references or search). Any feedback on the conversion so far would be appreciated. If everyone is generally happy with the direction this takes us, we can follow up with a cleanup and reorganisation of the documentation to make the structure more logical and consistent, and remove duplicated or obsolete parts. And then we can repeat the conversion for the manual page content as well. Kind regards, Roger From: Tiff <[email protected]> On Behalf Of [email protected] Sent: 01 June 2022 18:11 To: [email protected] Subject: [Tiff] Conversion of HTML documentation to Sphinx ReStructuredText (RST) Hi folks, 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. Kind regards, Roger
_______________________________________________ Tiff mailing list [email protected] https://lists.osgeo.org/mailman/listinfo/tiff
