Page 1 of 1

docs as pdf are missing

Posted: Sat Dec 19, 2020 1:11 am
by hcet14
Hello I'm new with Micropython,
since I want to read about, I found out the pdf is missing. http://docs.micropython.org/en/v1.13/mi ... n-docs.pdf and http://docs.micropython.org/en/latest/m ... n-docs.pdf are empty.

Re: docs as pdf are missing

Posted: Mon Dec 21, 2020 9:01 am
by pythoncoder
I don't think these are routinely built. You can build a local copy of the docs, in HTML or PDF form, by following these instructions.

Re: docs as pdf are missing

Posted: Tue Dec 22, 2020 11:49 am
by hcet14
Thanks for your answer, but I'm a complete linux beginner and have no clue about latex :(

After solving some problems, I get this
  • Makefile:
    latexpdf: cpydiff
    $(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
    @echo "Running LaTeX files through pdflatex..."
    $(MAKE) -C $(BUILDDIR)/latex all-pdf
    @echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
...but no pdf.

Line 128 in Makefile: $(SPHINXBUILD) $(FORCE) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex

Any idea?

Re: docs as pdf are missing

Posted: Tue Dec 22, 2020 3:34 pm
by scruss
I don't think this route is particularly well tested, as PDF docs via LaTeX are a completely separate and complex workflow.

At the very least, latexmk is required to get the make process to even begin. This isn't in the docs/README.md

I get a completely different kind of error in the build process where pdflatex is failing to handle UTF-8 characters, starting with the line:

Code: Select all

When buffering is enabled the DAC pin can drive loads down to 5KΩ.
This is odd, as sphinx is putting \usepackage[utf8]{inputenc} in the document. xelatex builds the document (with lots of warnings) but doesn't render the Ωs. I end up with a 350+ page PDF with some ropey paragraph layouts.

I used to be a TeX guy, but that was a very long time ago.

Re: docs as pdf are missing

Posted: Wed Dec 23, 2020 9:47 am
by pythoncoder
@hcet14 Out of interest why do you want this? You could build a local HTML image which provides all the docs during an internet outage. That build process always seems to run smoothly.

Re: docs as pdf are missing

Posted: Wed Dec 23, 2020 9:56 am
by hcet14
@scruss I tried your suggestion with latexmk, no difference. Thanks anyway.
I also tried pdftex MicroPython.tex since I get a tex file. But also no output file.

@pythoncoder I prefer pdfs for reading. make html runs smooth here without errors. As I stated above, I'm a complete linux beginner and have no clue about latex. Maybe I can learn something ;)

Re: docs as pdf are missing

Posted: Thu Dec 24, 2020 1:55 am
by scruss
I suspect this will be harder than it looks. Every tool I know about (Calibre, weasyprint, wkhtmltopdf, pandoc) failed to make a PDF from the source HTML. The document sources need to be fixed by the authors so that "make pdf" will work.

"make epub" works if you want a static, pageable document file.

Re: docs as pdf are missing

Posted: Thu Jan 14, 2021 11:43 pm
by mattyt
The core team are aware of the failures but haven't been able to resolve the issue (something to do with missing font characters?). If anyone can help out a PR would be very welcome!

Re: docs as pdf are missing

Posted: Mon Jan 18, 2021 4:25 am
by scruss
I think I've worked it out … please see PR #6779 Enable PDF doc generation

It requires an absolutely gargantuan TeX Live¹ download to get the correct fonts. For those who just want to see the current manual, here's a link to download one I just generated: MicroPython.pdf.

---
¹: I knew the late Sebastian Rahtz, the founder of the TeX Live project, when I was a UK TeX User Group board member. The first version fit a full TeX distribution for Windows, Mac OS and most Unix/Linux systems on a single CD-ROM, and it's fair to say that TeX Live has kept the system alive and useful. To build the MicroPython manual I had to download more than a CD-ROM full of just fonts for TeX Live. I'm not sure if Seb would be amused or horrified …