Please bring back the PDF documentation

[pschneider1968]

Documentation

In 3.14, the PDF documentation vanished. This is an extremely bad decision. You as the Python developers might not need this documentation at all, but I am a user, not a developer, and I absolutely need accessible, well formatted PDF documentation.

You cannot have such a widely used development language and then, all of a sudden, stop providing essential documentation in the most important format.

Please bring it back urgently!

Linked PRs

• gh-139741: Make dist-pdf docs archive build work for macOS #140837
• [3.14] gh-139741: Make dist-pdf docs archive build work for macOS (GH-140837) #141229
• [3.13] gh-139741: Make dist-pdf docs archive build work for macOS (GH-140837) #141230

[AA-Turner]

Hi Peter,

Thank you for opening this issue. I'd note that we had extensive discussions about the PDF documentation, spanning several months: https://discuss.python.org/t/101343/. Currently, the PDF archives are not well maintained, eg they do not meet the presentational standards I would expect of a technical manual.

We do continue to publish both the online HTML documentation, downloadable archives of the HTML documentation, and an EPUB document containing the entirety of the Python documentation. I would be curious as to which, if any, of these would be a suitable replacement for your needs, and if none, the reasons they're not suitable substitutes.

This isn't a decision I took lightly, and if there were a way to reintroduce PDFs without the significant maintenance burden I would gladly do so, but sadly it is not so.

I hope this provides some context as to the changes we've made.

Thanks,
Adam

[StanFromIreland]

I suggest moving this to Discourse rather than this tracker.

[pschneider1968]

We do continue to publish both the online HTML documentation, downloadable archives of the HTML documentation, and an EPUB document containing the entirety of the Python documentation. I would be curious as to which, if any, of these would be a suitable replacement for your needs, and if none, the reasons they're not suitable substitutes.

I looked at both the HTML archive and the EPub. The EPub is basically all documents lumped together in one single file. It takes ages to load (with Calibre on Windows), and it is very slow to navigate. Paging up and down takes seconds. I dont see this with any other EPub documentation I have (and I have a lot!) To be more useful, it would need to be split like the PDF docs were: one file per document; and it needs to have proper metadata so as to be able to have multiple Python version EPub docs in the library and be able to tell them apart. Currently, the title is just "Python".

The HTML docs are not as easily navigable as the PDF and the EPub because they don't have a permanent TOC on the left pane; instead most of the time the TOC is embedded in the page itself. It's not easy to get an overview this way. And I prefer not to have to use my browser to read the docs; because most if not all of my other programming related docs is PDF. E.g. just look at the PostgreSQL documentation: they manage to do a beautiful and properly updated new PDF of ~3000 pages with each and every release; just like you used to do it up until now!

The Python PDFs were just perfect: nice TOC, beautifully layout and fonts, and they were more easily accessible by a screen reader and easier to do a full text search.

That the PDFs are now missing is, for me, a major regression. You have taken away from me what I was used to for many years, and what I loved because of the quality and accessibility.

I didn't notice the discussion that was going on re the removal. I'm just a user, so I'm not monitoring feature and development discussions; if I had noticed, I would have vehemently opposed the removal.

I feel that if you would make a survey among users, the majority of them would miss the PDF docs like I do. Please bring them back!

[AA-Turner]

The HTML docs ... don't have a permanent TOC on the left pane; instead most of the time the TOC is embedded in the page itself.

I'd be interested to know more here, at least on desktop each page has its (local) table of contents in the left hand sidebar. Have you seen https://docs.python.org/3/contents.html, which contains the global TOC?

A

[adqm]

Have you seen https://docs.python.org/3/contents.html, which contains the global TOC?

I think the TOC page could do with some reorganization to make it as useful as the typical PDF viewer's TOC pane. Right now, the sidebar navigation there doesn't have anything useful in it, and one has to scroll manually past a huge amount of "what's new in Python" subsections to get to the more-useful parts of the docs.

My default PDF viewer has collapsible sections in the TOC. So when I first open it I get a view of only the top-level sections, but I can expand each one to get the next layer, and so on. Adjusting the full TOC to mimic that behavior would make it more usable IMO.

Or there are smaller changes that might help: maybe reordering the TOC entries would help, and/or limiting things to one or two levels of sections, and/or probably other things we could think about.

I also didn't know that that page existed until right now, so maybe there's a way to make it more discoverable? A sidebar link under the page's TOC to the global TOC?

I'd be happy to have a go at implementing any of those changes if it feels like they might be useful.

[pschneider1968]

The HTML docs ... don't have a permanent TOC on the left pane; instead most of the time the TOC is embedded in the page itself.

I'd be interested to know more here, at least on desktop each page has its (local) table of contents in the left hand sidebar. Have you seen https://docs.python.org/3/contents.html, which contains the global TOC?

A

As an example, from the Python tutorial document (1st screenshot). The TOC is in the document pane, and on the left sidebar is only the TOC of the current chapter! That's really awful (sorry!) and not really usable, compared to the PDF version (2nd screenshot).

[Naitreey]

In the download page, it says:

We no longer provide pre-built PDFs of the documentation. To build a PDF archive, follow the instructions in the Developer's Guide and run make dist-pdf in the Doc/ directory of a copy of the CPython repository.

During the build, I encountered this error:

/Applications/Xcode.app/Contents/Developer/usr/bin/make: unrecognized option `--output-sync'

OK, it turns out only GNU make is supported. Maybe this should be made clear in the guide.

Now, I only want to add my own personal need for pdf docs: I put the pdf doc archives into my personal full-text indexed database (using a software called DEVONthink, by the way), so I can find relevant information more easily. HTML archive won't work, because it also contains scripts, image, sources, etc. many sorts of files in the archive.

[m-aciek]

Following change in the Doc/Makefile is needed to make the dist-pdf work for MacOS, keeping Linux support:

Index: Doc/Makefile
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/Doc/Makefile b/Doc/Makefile
--- a/Doc/Makefile	(revision f4e6370582380b12286b6f5b625c282eaf12c84a)
+++ b/Doc/Makefile	(date 1761641930847)
@@ -241,7 +241,7 @@
 	# as otherwise the full latexmk process is run twice.
 	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
 	-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
-	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
+	(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`getconf _NPROCESSORS_ONLN`+1)) LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
 	cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
 	cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
 	@echo "Build finished and archived!"

@Naitreey would you care to open a PR with those changes?

[Naitreey]

@m-aciek Sorry for the delayed reply. Thank you for providing the necessary changes and PR suggestion. I think output sync is something good to have if possible. So I used a conditional to deal with macOS's default make. See the PR.