search

ewjoachim / sphinx-github-changelog

Build a sphinx changelog from GitHub Releases
https://sphinx-github-changelog.readthedocs.io
MIT License
26 stars 4 forks source link

Changelog in pdf build lacks description #122

Open christian-herber-nxp opened 6 months ago

christian-herber-nxp commented 6 months ago

The changelog in html looks great, but when building a pdf, the changelog only has the tag and title, but lacks the descriptive text of the changelog.

ewjoachim commented 6 months ago

I have to admit that I never looked at anything else than the [EDIT] HTML version. Would that be something you would consider contributing ?

christian-herber-nxp commented 6 months ago

When you say PDF, you mean html? Being able to contribute to a repository requires quite some corporate effort, which is likely not reasonable. I did have a look at the code, but nothing obvious seemed there which could cause the observed behavior.

ewjoachim commented 6 months ago

When you say PDF, you mean html?

yes sorry.

Being able to contribute to a repository requires quite some corporate effort

Well either that or contributing on your own time, which might be even more unreasonable, thus this. Just wanted to mention that, while I admit I have no idea what the proportion is, a large proportion of overall open-source work (and about 100% of this repo) is volunteer work, with none of the development time being compensated. This repo is me thinking that the project should exist and making it for no other goal than being satisfied that it exists (and able to use it in other similar projects). While I acknowledge that there are a lot of issues in the fact so much open-source work is unpaid work on top of which companies can build profit, I find your wording odd (though I'm not taking any offense or anything) that you tie open-source solely to corporate effort. And again, you're totally entitled to have a personal life free of any open-source volunteer commitments, the only thing I'm noticing is your wording describing this as a fact where open-source is, as far as I can tell, one of humanity's most impressive collaborative achievement that is empowering everyone and (somewhat) not solely led by companies or "traditional" politics.

christian-herber-nxp commented 6 months ago

I highly value your contribution with this package. I do not expect you to fix any issues I am posting. But reporting an issue I am observing is contributing to your project in the way that is possible for me. It would be appreciated if you can state if this is something that you are intending to fix or not.

ewjoachim commented 6 months ago

It would be appreciated if you can state if this is something that you are intending to fix or not.

Yep, though I have no idea whether this will happen in a foreseeable timeline or not.

It probably helps if you have a reproducer. Not having one doesn't mean I won't work on it either. I mainly don't know.

ewjoachim commented 6 months ago

Ah here's a reproducer: https://docs.openhwgroup.org/_/downloads/openhw-group-core-v-xif/en/latest/pdf/

Perfect.

ewjoachim commented 6 months ago

Ok, the reason why it happens is that the description HTML is passed to the parser as raw, so it's untouched. If the output format is html, it works. If it's any other format it doesn't.

How to fix that: we need to parse either the HTML or the GitHub-flavored Markdown or the html into docutils nodes. I think myst-parser should be able to do it but after an hour searching, I don't understand how.

I'm not sure I'm passionate enough to spend more time on that right now but if anyone has an idea, feel free.

I've asked in the myst-parser discussions.

ewjoachim commented 6 months ago

For the record, I posted here a script to setup a repo that uses sphinx-github-changelog, and here are the additional commands one may use to reproduce this issue in particular:

You'll need a latex distribution supporting tlmgr. Also, it works on MacOS and I believe it works on Linux. Here are the tlmgr plugins you'll need:

sudo tlmgr install latexmk tex-gyre fncychap wrapfig capt-of framed needspace tabulary varwidth titlesec

Build with

make -C docs SPHINXOPTS=-EW clean latexpdf

And then open docs/build/latex/sphinx-github-changelog-devenv.pdf.

I believe the same fix will fix both issues #120 and #122.

christian-herber-nxp commented 6 months ago

which system are you running this on? I tried to get this running on WSL Ubuntu-22.04, but it seems non-trivial, as the tlmgr version is sort of old. Is what you are describing a workaround or will this be the long term solution?

christian-herber-nxp commented 6 months ago

Looking into this a bit further, it seems that debian strongly discourages texlive in favor of apt. While it is probably possible to patch up a working version of texlive under ubuntu and somehow get this running, this might lead to a too high hurdle for people to be able to reproduce a build (and also getting it running on readthedocs), and is actually unnecessary.

On Ubuntu 22.04, all of the mentioned packages are contained in texlive-latex-extra, which i have installed. Still, using your command, the changelog does not build properly.

ewjoachim commented 6 months ago

which system are you running this on?

I ran it on macOS. Yeah, on an ubuntu (or WSL), I guess APT makes sense.

Is what you are describing a workaround or will this be the long term solution?

Neither. It's a way to setup one's computer if we needed to launch the code locally so as to study it in details. Note that it's perfectly reasonable to reimplement the way Docutils nodes are produced, and then test it on ReadTheDocs directly, without installing the latex stack locally. As I said:

here are the additional commands one may use to reproduce this issue in particular

Sorry for the confusion.

bedilbek commented 4 months ago

Hi @ewjoachim, thanks for this amazing project. Is there any progress going on with this issue? Or what kind of help is needed to fix it?