ENH: Enable PDF book style build via LaTeX

[AakashGfude]

This PR enables the book style PDF to be built via LaTeX.

Changes:

Upgrading to mathjax v3 to use textmacros was necessary, to escape _ inside \text{} as it is a special character. https://github.com/QuantEcon/lecture-datascience.myst/compare/pdf-changes?expand=1#diff-596037ac6201ed91873ef81f374bc604c6c1f0a4d56833e749433585288d7b1eR135

NOTE that while using _ or any special characters inside \text{} we need to escape it. Like its done in this PR by using \_ instead of _

{align*} is an environment, which throws errors in latex, when its inside another environment like $$ . Using {aligned} instead is the way to go.

[mmcky]

{align*} is an environment, which throws errors in latex, when its inside another environment like $$ . Using {aligned} instead is the way to go.

Thanks @AakashGfude 👍 -- this is because aligned is not a full math environment so can be used within the $$. I will add an update to https://manual.quantecon.org/writing/styleguide.html#mathematical-notation with a better explanation for the quantecon style guide.

[mmcky]

@AakashGfude I presume these aren't required for datascience

[AakashGfude]

they are already added in quantecon-book-theme for mathjax v3. https://github.com/QuantEcon/quantecon-book-theme/blob/master/quantecon_book_theme/layout.html#L10 .

Since, there is no variable in sphinx to add configuration for mathjax3 in config file. I think it should be introduced in sphinxv4 though.

[mmcky]

the new variable in sphinx version 4+ is mathjax3_config

[mmcky]

@AakashGfude I have opened a issue to track that inclusion

QuantEcon/quantecon-book-theme#167

[mmcky]

@AakashGfude just for clarity for when I update the style guide we need to escape the _ right?

This change QuantEcon/quantecon-book-theme@ec8d8c8 will then enable the correct Tex to be processed by mathjax.

[AakashGfude]

Yes, if we want to write a literal underscore, then we will have to escape it like that. http://docs.mathjax.org/en/latest/input/tex/extensions/textmacros.html#quoted-special-characters . I was about to comment about mentioning textmacros in the style guide as well http://docs.mathjax.org/en/latest/input/tex/extensions/textmacros.html

[mmcky]

that would be great -- can you remind me or open an issue on: QuantEcon.manual

[AakashGfude]

@mmcky what is QuantEcon.manual ?

[mmcky]

• update environment.yml to include quantecon-book-theme==0.2.8

Actually this is taken care of for automatic minor version updates:

    - quantecon-book-theme>=0.2.5,<0.3.0

[AakashGfude]

quantecon-book-theme 0.2.8 is now released.

[mmcky]

@AakashGfude is there a package I need to add to support the image conversion?

[mmcky]

@AakashGfude do the image file references need support for folders?

../_build/jupyter_execute/working_with_text_52_0.png

or is this directory a flat collection if images?

[mmcky]

@AakashGfude I just ran this branch locally -- it seems to build the pdf. Perhaps the images are not getting "written" in the server environment (or saved from the execution steps). Hmm ....

Actually my local jupyter_execute is organised in folders

lectures/_build/jupyter_execute  adjust-toc ✔                                                                                         2m  
▶ ls
applications        index.py            pandas              python_fundamentals theme
index.ipynb         introduction        problem_sets        scientific

[mmcky]

@AakashGfude I have opened #194 to update _toc.yml into jb-book format for better pdflatex outputs.

• merge MAINT: Adjust _toc.yml to adopt jb-book format structure #194

[AakashGfude]

@mmcky , i think the path is different in server than in local? Is their an artifact we can download?

[AakashGfude]

@mmcky actually the path generated is wrong altogether, as the file it is trying to find, for example, is '../_build/jupyter_execute/plotting_5_1.png' but the file is in path jupyter_execute/scientific/plotting_5_1.png

[mmcky]

yeah -- that's right. It seems to be missing the nested folder (scientific) right?

[AakashGfude]

yeah -- that's right. It seems to be missing the nested folder (scientific) right?

@mmcky But also, locally it is noindent\sphinxincludegraphics{{plotting_5_1}.png} in tex file, . the images ideally get copied to where the tex file is in the _build/latex folder and it accesses that one instead of the one in jupyter_execute

[mmcky]

yeah -- that's right. It seems to be missing the nested folder (scientific) right?

@mmcky But also, locally it is noindent\sphinxincludegraphics{{plotting_5_1}.png} in tex file, . the images ideally get copied to where the tex file is in the _build/latex folder and it accesses that one instead of the one in jupyter_execute

How do they avoid conflicts -- is that _5_1 in chapter 5 section 1? Or just a numbering system in that file as in (-)

[mmcky]

@AakashGfude the _build folder is available

https://github.com/QuantEcon/lecture-datascience.myst/actions/runs/1357596935

under artifacts

[mmcky]

@AakashGfude so the _build folder from github actions doesn't have any of the png images in _build/latex unlike the local build. So the images are not getting copied over (as you say).

[AakashGfude]

@AakashGfude so the _build folder from github actions doesn't have any of the png images in _build/latex unlike the local build. So the images are not getting copied over (as you say).

Hmm, will check what is 'cause' and what is 'effect' here

[mmcky]

@AakashGfude so the _build folder from github actions doesn't have any of the png images in _build/latex unlike the local build. So the images are not getting copied over (as you say).

Hmm, will check what is 'cause' and what is 'effect' here

@AakashGfude what confuses me is that the other repos are building on github actions just fine. So it must be something to do with this repo structure such as nested folders.

[AakashGfude]

This PR has been halted from merging, because of HTML build failing. Which is caused by the server of Canadian government, geolocation service being currently down. https://www.nrcan.gc.ca/science-and-data/science-and-research/earth-sciences/geography/topographic-information/web-services/geolocation-service/17304

[mmcky]

@AakashGfude hopefully this server issue is now resolved. So could you re-trigger the CI to check.

[AakashGfude]

@mmcky I did run it again, and got the following error.
working_with_text.log

Some nltk issue, 9omw-1.4 not found.

[mmcky]

@mmcky I did run it again, and got the following error. working_with_text.log

Some nltk issue, 9omw-1.4 not found.

Is this on your local? I saw the CI last ran on 3rd Jan.

Roger that. @jbrightuniverse any ideas on how to resolve this nltk issue?

[jbrightuniverse]

according to those logs:

  Resource �[93momw-1.4�[0m not found.
  Please use the NLTK Downloader to obtain the resource:

  �[31m>>> import nltk
  >>> nltk.download('omw-1.4')
  �[0m
  For more information see: https://www.nltk.org/data.html

it seems that a language set is missing? the logs claim executing that line at some point in the build would solve it; I'm not familiar with the codebase so I'm not sure if that already happens or if the set is expected to already be there. Also notable is the logs claim:

  Attempted to load �[93mcorpora/omw-1.4.zip/omw-1.4/�[0m

  Searched in:
    - '/home/runner/nltk_data'
    - '/usr/share/miniconda3/envs/lecture-datascience/nltk_data'
    - '/usr/share/miniconda3/envs/lecture-datascience/share/nltk_data'
    - '/usr/share/miniconda3/envs/lecture-datascience/lib/nltk_data'
    - '/usr/share/nltk_data'
    - '/usr/local/share/nltk_data'
    - '/usr/lib/nltk_data'
    - '/usr/local/lib/nltk_data'