docs as pdf are missing

General discussions and questions abound development of code with MicroPython that is not hardware specific.
Target audience: MicroPython Users.
Post Reply
User avatar
hcet14
Posts: 14
Joined: Sat Dec 19, 2020 12:59 am

docs as pdf are missing

Post by hcet14 » Sat Dec 19, 2020 1:11 am

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.

User avatar
pythoncoder
Posts: 4929
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: docs as pdf are missing

Post by pythoncoder » Mon Dec 21, 2020 9:01 am

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.
Peter Hinch

User avatar
hcet14
Posts: 14
Joined: Sat Dec 19, 2020 12:59 am

Re: docs as pdf are missing

Post by hcet14 » Tue Dec 22, 2020 11:49 am

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?
I'm a beginner with this stuff and no programmer at all.

scruss
Posts: 38
Joined: Sat Aug 12, 2017 2:27 pm

Re: docs as pdf are missing

Post by scruss » Tue Dec 22, 2020 3:34 pm

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.

User avatar
pythoncoder
Posts: 4929
Joined: Fri Jul 18, 2014 8:01 am
Location: UK
Contact:

Re: docs as pdf are missing

Post by pythoncoder » Wed Dec 23, 2020 9:47 am

@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.
Peter Hinch

User avatar
hcet14
Posts: 14
Joined: Sat Dec 19, 2020 12:59 am

Re: docs as pdf are missing

Post by hcet14 » Wed Dec 23, 2020 9:56 am

@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 ;)
I'm a beginner with this stuff and no programmer at all.

scruss
Posts: 38
Joined: Sat Aug 12, 2017 2:27 pm

Re: docs as pdf are missing

Post by scruss » Thu Dec 24, 2020 1:55 am

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.

User avatar
mattyt
Posts: 329
Joined: Mon Jan 23, 2017 6:39 am

Re: docs as pdf are missing

Post by mattyt » Thu Jan 14, 2021 11:43 pm

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!

scruss
Posts: 38
Joined: Sat Aug 12, 2017 2:27 pm

Re: docs as pdf are missing

Post by scruss » Mon Jan 18, 2021 4:25 am

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 …

Post Reply