Known issues in the PDF format of the PyGMT documentation

[seisman]

This is the central issue to report/discuss the issues in the PDF format of the PyGMT documentation. The PDF file for the dev version (reflecting the main branch) is available at https://www.pygmt.org/dev/pygmt-docs.pdf.

• On the first page, it say 'Author name not set'. It would be nice if we could grab the names from the CITATION.cff file somehow. [Set to "The PyGMT Developers" in PR DOC: Fix the author information and the structure in the PDF documention #3840]

• Missing emojis, unsure if there's anyway to show them in LaTeX (if it involves downloading a large font file, we can skip it)
  

• In the PDF file, the 'PyGMT Team' section lists everyone's profile pictures on 1 page (at a low-resolution). Unsure if there's a way to make those photos smaller.

Originally posted by @weiji14 in #3765 (review)

• Weird / confusing structure compared to the website. It looks like the sections of the README are used as chapter headings, and all sections on the website are listed under "Related topics", which is the last section of the README. [Fixed in DOC: Fix the author information and the structure in the PDF documention #3840]

website side bar	PDF contents

• The content of README.md is not included [See the reason in DOC: Fix the author information and the structure in the PDF documention #3840]

[seisman]

[ ] On the first page, it say 'Author name not set'. It would be nice if we could grab the names from the CITATION.cff file somehow.

Grabbing names from the CITATION.cff file means parsing the YAML file, which is extra coding efforts. In PR #3840, I have set the authors to "The PyGMT Developers" instead.

[ ] Missing emojis, unsure if there's anyway to show them in LaTeX (if it involves downloading a large font file, we can skip it)

Currently, we type emojis directly into the text. It works well for HTML, but it doesn't work for LaTeX. If you check the TeX source files generated by make pdf, you will see that the raw emoji unicode characters are directly shown in the text. However, the LaTeX emoji package (https://ctan.math.washington.edu/tex-archive/macros/luatex/latex/emoji/emoji-doc.pdf
) expects a syntax like \emoji{joy} instead. A possible solution is sphinxemoji, but its syntax (|:heart_eyes:|) likely doesn't work in Markdown.

Actually, I'm thinking if we should remove the changelog section from the PDF documentation.

[ ] In the PDF file, the 'PyGMT Team' section lists everyone's profile pictures on 1 page (at a low-resolution). Unsure if there's a way to make those photos smaller.

Related to upstream issue executablebooks/sphinx-design#179. No solutions yet.

• Weird / confusing structure compared to the website. It looks like the sections of the README are used as chapter headings, and all sections on the website are listed under "Related topics", which is the last section of the README.

website side bar PDF contents

Yes, this is because we directly include the README file in the doc's index.md file:

pygmt/doc/index.md

Lines 12 to 16 in eb0ebe7

	```{include} ../README.md
	:start-after: <!-- doc-index-start-after -->
	:end-before: <!-- doc-index-end-before -->
	:relative-images:
	```

I don't have a perfect solution yet, but PR #3840 fixes the PDF structure by excluding the README file from the PDF output.