Do not build/publish pdf #1763
Do not build/publish pdf #1763
Conversation
|
I believe there currently is a bug somewhere, seems like it's building 5000+ pages pdf currently. https://github.com/atomvm/AtomVM/actions/runs/16346050012/job/46179902901 Either way, I think they are at least valuable for releases, and maybe on the main/release-0.6 branch. |
We have definitely had requests for PDF and epub documentation in the past, I don’t know if those people are still interested in the project. I suppose we could remove them and wait and see if we get any complaints. |
I have seen this happen before when there was a formatting typo… in this case it appears to be the changes you made to CHANGELOG.md, but at a glance I can’t tell you why… your changes look correct to me. |
|
Right now, our PDF documentation is not in a great shape: 
Also I'm still thinking that we should really start using ExDoc, at least for Elixir and Erlang documentation, and in that case we would loose pdf/epub formats anyway |
I have been thinking the same thing, I did not want to end up with multiple themes again, that is distracting and unpleasant. There is some motion again on having exdoc output markdown. I was holding off to see how soon that happens. When that option becomes available we can continue to use the same unified theme we use now. If we make the change to generating all of the documentation with exdoc I would like to find a way to include the C APIs. So far I cannot find a way to parse either the doxygen comments directly or the doxygen generated xml to include the C APIs in the exdoc generated documentation. |
Why not using exdoc for converting markdown to HTML, and focusing into producing markdown from doxygen? |
|
Also, I think we should merge this, unless we found how to make epub/pdf output work again. |
I looked into this, the markdown produced by doxygen is somewhat a mess. Most of the useful information is not included and it seems to just be an unorganized outline. The solution @petermm shared on Telegram of using exdoc to parse the doxygen xml looks by far the most promising, that would allow us to create all of the documentation using exdoc - maintaining a single theme. By the way exdoc does support ePUB, so we won’t loose that, just PDFs. I think as long as we have one portable download option for the docs that is sufficient. |
bettio
force-pushed
the
do-not-publish-pdf-epub
branch
from
29d388a to
4a08324
Compare
Done. |
Remove PDF generation, keep just one offline format (epub). Remove pdf since it is not the ideal format (and also we'll use epub the day we'll switch to ex_doc). Signed-off-by: Davide Bettio <[email protected]>
bettio
force-pushed
the
do-not-publish-pdf-epub
branch
from
4a08324 to
da6d0e0
Compare
Despite the branch name, we are just discarding PDF build.
We just keep one format for offline viewing, that is also the format used from other tools (such as ex_doc) and it has less quirks while building it.
These changes are made under both the "Apache 2.0" and the "GNU Lesser General
Public License 2.1 or later" license terms (dual license).
SPDX-License-Identifier: Apache-2.0 OR LGPL-2.1-or-later