Design Decisions for LaTeX/PDF Support

[mmcky]

The following documents the design strategy for making improvements to LaTeX/PDF (via LaTeX) support for jupyter-book. It is intended to bring some of the details and decision making up to the top for those interested in how it works and hopefully the design strategy helps improve contributions.

We have elected to keep using the default sphinx latex writer as it provides a lot of good / establish work on translating the Sphinx AST into TeX and solves a lot of translation issues using Sphinx macros that are established.

Therefore we decided to use transforms to alter the AST to shape it in a way that brings harmony between HTML outputs and PDF outputs in terms of numbering and structure of the document. These transforms are contained in jupyterbook-latex

All latex improvements are currently contained in a jupyterbook package jupyterbook-latex so the code is separate to the cli and other jupyter-book config logic to piece elements together.

Here is the current feature list

Development Roadmap

PR jupyter-book:#1167 is the initial release focused on bringing harmony to html and latex outputs (in terms of document structures), support jupyter-book directive tableofcontents, and support for commonly used tags on code-cell directives such as hide-cell. [Target: Whole of Project PDF]

Next Steps:

1. Work on latex:pdf issues and other listed issues
2. Work on --individualpages support for improved PDF generation at the page level (via LaTeX)
3. Improve support and coverage of all tags and jupyter-book features

Throughout this process we will need to think about how to support more complex structures in PDF such as panels through a review of the following categories:

1. implement an alternative static representation of the objects
2. require the use of a companion html based website with links to support dynamic content
3. don't support some objects in LaTeX and throw warnings.

[choldgraf]

@mmcky a quick thought on this roadmap - do you think it'd be helpful to create a github project board in the executablebooks/ organization that tracks this project moving forward? I think it'd be a more natural place to look than to dig into this issue for "roadmap" content

[mmcky]

project board? I agree -- issues / Discussions is a funny place. Happy to move + update it.