search

OBF / obf-docs

Official documents of the Open Bioinformatics Foundation
39 stars 20 forks source link

Updates PDF and HTML conversions of bylaws #120

Closed hlapp closed 2 months ago

hlapp commented 2 months ago

Fixes #119

hlapp commented 2 months ago

Yes, whenever there is a major change in the Pandoc version used for conversion, there's a potential for everything changing even though all that's really changed is Pandoc.

All I did here was using Pandoc to regenerate the HTML and PDF versions from the OBF Bylaws.md document (which is what we're treating as the master document and thus subject to voting for approval). I used Pandoc version pandoc 3.1.1 for both conversions, and pdfTeX 3.141592653-2.6-1.40.26 (TeX Live 2024) is the version of pdflatex used by pandoc in producing the PDF.

The actual change should be the exact same as the change to the Markdown document resulting from PR #102.

peterjc commented 2 months ago

You can split the commit in two for this kind of situation (rebuild from (missing word) the old markdown file with the new version of pandoc which gives the formatting changes, and then rebuild with the new markdown files which gives the expected changes). However that's quite fiddly and still boils down to trusting the first commit is as described.

We see similar "churn" or "noise" with the Biopython HTML documentation https://github.com/biopython/docs/ on the rare occasions we change the version of Sphinx used to generate it.

hlapp commented 2 months ago

Note that pandoc is not rebuilding the markdown file, or changing it in any way. Perhaps there's a misunderstanding as to what this change is. It's not making any change to the Bylaws in the form of the markdown document. So I think this is already the split you're suggesting?

peterjc commented 2 months ago

Sorry, missed a "from" which did change the meaning rather. I was talking about potentially separating the changes due to the tooling from the changes in the source markdown file.

(As an aside, we could in theory run pandoc via continuous integration to automatically general the HTML and PDF files from the markdown. This is probably doable for the HTML but last time I checked the LaTeX dependency is too big for automated PDF output to be practical. This was one of the reasons Biopython moved away from writing our documentation in LaTeX)

hlapp commented 2 months ago

As an aside, we could in theory run pandoc via continuous integration to automatically general the HTML and PDF files from the markdown. This is probably doable for the HTML but last time I checked the LaTeX dependency is too big for automated PDF output to be practical.

Indeed I was thinking the same thing, with the same concern. (Did you try a custom container? The pandoc/latex container is <1GB, and seems to be designed to be usable for GH Actions, given some of the documentation.)

The alternative could be to simply drop the HTML and PDF versions.

cjfields commented 2 months ago

As an aside, we could in theory run pandoc via continuous integration to automatically general the HTML and PDF files from the markdown. This is probably doable for the HTML but last time I checked the LaTeX dependency is too big for automated PDF output to be practical.

Indeed I was thinking the same thing, with the same concern. (Did you try a custom container? The pandoc/latex container is <1GB, and seems to be designed to be usable for GH Actions, given some of the documentation.)

The alternative could be to simply drop the HTML and PDF versions.

I think if we do want to retain the HTML/PDF versions we must have a CI solution in place to ensure they are up to date.

peterjc commented 2 months ago

If the LaTeX CI is still impractical (TBC), then running pandoc to make the HTML version sounds much more realistic. We might then compromise by dropping the PDF output?

peterjc commented 2 months ago

Thanks all.