Skip to content

Commit f1b71f2

Browse files
author
Release Manager
committed
sagemathgh-39325: [DOC] Allow Sphinx PDF build to reflow long decimal expansions in code-blocks to avoid them extending beyond page limits <!-- ^ Please provide a concise and informative title. --> <!-- ^ Don't put issue numbers in the title, do this in the PR description below. --> <!-- ^ For example, instead of "Fixes sagemath#12345" use "Introduce new method to calculate 1 + 2". --> <!-- v Describe your changes below in detail. --> <!-- v Why is this change required? What problem does it solve? --> <!-- v If this PR resolves an open issue, please link to it here. For example, "Fixes sagemath#12345". --> Update conf.py's for A Tour of Sage in PDF format to fix long decimal expansions. Before: ![Capture d’écran 2025-01-14 à 12 28 46](https://github.com/user- attachments/assets/34619477-6940-4b75-9655-b4a29f74cbce) ![Capture d’écran 2025-01-14 à 12 27 29](https://github.com/user- attachments/assets/bcdd363e-b78e-4e1f-beaa-c069fcc10c17) After: ![Capture d’écran 2025-01-14 à 12 09 05](https://github.com/user- attachments/assets/000d6148-43d6-4a14-8fcd-b408f5c5afa0) Additional notes: EDIT The below is partially obsolete. The change has been moved to `sage_docbuld/conf.py` following sagemath#39325 (comment) - I took the "before" screenshot from [official PDF](https://doc.sagemath.org/pdf/en/a_tour_of_sage/a_tour_of_sage.pdf) and the "after" from building locally on a checkout of develop branch, which may explain a number of differences which are not related to the PR at all, - the PR only has an impact on wrapping lengthy lines in code-blocks, - To build the PDFs locally, I copied over the conf.py, index.rst and image files to a fresh sphinx empty project with some adaptations to conf.py to avoid importing Sage modules which I did not install in my environment, because I feared the whole thing might be a very long process and I am not familiar with Sage and Sage repository. I simply forked it to be able to submit this PR. - I removed from the French language conf.py some stuff about `\at` LaTeX control sequence needing to be undefined to avoid conflict with babel-french, because I am not aware of Sphinx defining any `\at` at all in the preamble it creates in output `.tex` file, I suspected this is long obsolete, there is no `\at` definition to be found in any of Sphinx LaTeX support files and I have never encountered such an issue in my practice of Sphinx with French language. - There is also some special configuration in the Italian conf.py which I simply copied over, not deleting. Its original syntax extends `latex_elements['preamble']` but except if there is some import during the build of some other conf.py, which appears not to be the case, a direct assignment as done in PR should be equivalent. - Tests of the PDF builds were done using latest Sphinx (8.1.3 and dev HEAD). - As explained above the PDF builds were done manually and not via the Sage build process which I feared might require me to install a bunch of additional dependencies, etc... which I did not do. So please double- check the effect on a genuine documentation build. The PR only affects the various A Tour of Sage documents but may perhaps be profitably extended to more Sage documentation in future. ### 📝 Checklist <!-- Put an `x` in all the boxes that apply. --> - [x] The title is concise and informative. - [x] The description explains in detail what this PR is about. - [ ] I have linked a relevant issue or discussion. - [ ] I have created tests covering the changes. - [ ] I have updated the documentation and checked the documentation preview. ### ⌛ Dependencies <!-- List all open PRs that this PR logically depends on. For example, --> <!-- - sagemath#12345: short description why this is a dependency --> <!-- - sagemath#34567: ... --> URL: sagemath#39325 Reported by: Jean-François B. Reviewer(s): Kwankyu Lee
2 parents 4e66964 + 4e0e9a8 commit f1b71f2

File tree

1 file changed

+5
-0
lines changed

1 file changed

+5
-0
lines changed

src/sage_docbuild/conf.py

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -647,6 +647,11 @@ def linkcode_resolve(domain, info):
647647
\makeatother
648648
"""
649649

650+
# Enable "hard wrapping" long code lines (only applies if breaking
651+
# long codelines at spaces or other suitable places failed, typically
652+
# this is for long decimal expansions or possibly long string identifiers)
653+
latex_elements['sphinxsetup'] = "verbatimforcewraps=true"
654+
650655
# Documents to append as an appendix to all manuals.
651656
# latex_appendices = []
652657

0 commit comments

Comments
 (0)