Open btashton opened 1 year ago
+1 :-) im here to help :-)
I took a stab at this today and have something I think is workable. Let me know if this pdf attached seems workable as a first pass.
@cederom @patacongo @hartmannathan
For my own reference
SPHINXOPTS='-D latex_engine=lualatex' pipenv run make latexpdf
webp
and gif
images to png (there are only two) since they cannot be rendered to tex.Looks awesome first step! Congratulation @btashton :-)
We could create a tar.gz packages for each release along with full pdf documentation. Then save it in various places and we are ready for zombie apocalypse! :-)
Some tweaking that comes to my mind at first look:
We need to shrink the full document size from 24MB to as small as possible. Would that be possible to see how small PDF can be with no images at all? I was using LaTeX for some time for documentation / presentation / automation so I have some experience we can use. From what I remember the best format for graphics was vector (where possible) as it results best quality and smallest size (LaTeX converted those to eps/ps and then attached to ps version of the document that was then coverted to pdf).. so we may try using SVG for the diagrams? As for PNG I also had to convert JPG to PNG.. but there may be some smart way around that.. or simply reworking final PDF with the trick below.
Quick trick I usually do to make PDF smaller without noticeable graphics quality loss is:
gs -sDEVICE=pdfwrite -dCompatibilityLevel=1.4 -dPDFSETTINGS=/screen -dNOPAUSE -dBATCH -dQUIET -dDownsampleColorImages=true -dColorImageResolution=200 -dColorImageDownsampleType=/Bicubic -sOutputFile=nuttx-small.pdf nuttx.pdf
Tuning the image resolution parameter I got (quality assessed on terminal screenshots modern 4K monitor):
Please let me know how can I help? :-)
I was able to quick-and-dirty try out the PDF build based on example sphinx conf [1] with some small adjutments.
sphinx-build -b latex . _build_latex -j8; cd _build_latex; gmake all
.
there are issues with some UTF characters that cannot be converted to LaTeX.
all images needs to be converted first to PNG (this can be done with convert
utility from ImageMagic).
due to LaTeX build errors I had to add -f
switch to pdflatex
in _build_latex/Makefile
. Also batch mode helps in build no questions asked (to be confirmed by Enter anyways). (PDFLATEX = latexmk -pdf -dvi- -ps- -f --interaction=batchmode
).
Resulting PDF is here: main.pdf :-)
It is 25MB in size, so probably text takes around 3MB.
The template used is kinda old.
There is a list of figures and tables (settings for LaTeX document).
There is a ToC navigation in PDF (settings for LaTeX document).
[1] https://sphinxguide.readthedocs.io/en/latest/sphinx_basics/settings.html
Tbh I'm probably not going to make too many tuning changes and what we can do are somewhat limited as this is generated via sphinx and some formatting is going to be opinionated from that.
What I will do is wire this up to be linked in the website for download.
As for the size. In this day and age is it really worth making it more optimized? 25MB is tiny compared to even the repo and the PDF is something like 300+ pages with images.
I personally expect minimal usage of this.
- Okay so I was able to build HTML documentation on FreeBSD. Images on the website take around 22.8MB.
- I was able to quick-and-dirty try out the PDF build based on example sphinx conf [1] with some small adjutments.
sphinx-build -b latex . _build_latex -j8; cd _build_latex; gmake all
.- there are issues with some UTF characters that cannot be converted to LaTeX.
- all images needs to be converted first to PNG (this can be done with
convert
utility from ImageMagic).- due to LaTeX build errors I had to add
-f
switch topdflatex
in_build_latex/Makefile
. Also batch mode helps in build no questions asked (to be confirmed by Enter anyways). (PDFLATEX = latexmk -pdf -dvi- -ps- -f --interaction=batchmode
).
You are reinventing what I have already done. Already resolved the Unicode issue and also all the images outside of two of them. There is no need to change the Unicode characters or bulk change images to png.
gs
conversion results above for a comparison. This trick comes handy quite often in various areas working with PDF. No commercial closed source converters involved :-)[1] https://asciinema.org/ [2] https://github.com/misc0110/asciicast2vector
@btashton: Tbh I'm probably not going to make too many tuning changes and what we can do are somewhat limited as this is generated via sphinx and some formatting is going to be opinionated from that.
It can be easily tuned in conf.py
and the LaTeX section from what I can see :-)
What I will do is wire this up to be linked in the website for download.
Awesome! Thank you! :-)
As for the size. In this day and age is it really worth making it more optimized? 25MB is tiny compared to even the repo and the PDF is something like 300+ pages with images.
Well, old habits, my butt hurts when the overall size can be easily decreased 3x+ and the text to gfx ratio is 1:9. I will try to help with gfx optimization + documentation edit / update no worries :-)
I personally expect minimal usage of this.
Even more kudos for doing that @btashton thank you ! :-)
Here goes the ePub test build: NuttX.epub.zip. I had to zip it for GH to accept the file, please unzip after download. You can use Calibre reader to open it [1] :-)
Right now we only export the html versions of the docs. There have been asks to also publish the PDF which should be low effort for us to do.