Make doc-pdf separate from doc-html #36692

kwankyu · 2023-11-10T14:32:00Z

(1) Fixes the issue in #36614 (comment) by making doc-pdf target separate from doc-html target.

(2) Support .. ONLY:: (introduced by #36495) in generating rst files for sage modules by the reference builder.

(3) Edited the pdf docs website to look consistent and tidy.

📝 Checklist

The title is concise, informative, and self-explanatory.
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 accordingly.

⌛ Dependencies

mkoeppe · 2023-11-10T15:56:27Z

From #36614 (comment), it seems like the PDF docbuild is still building HTML documentation?

mkoeppe · 2023-11-10T15:57:52Z

I think I have a fix for that in #36498 (87e40a3), please feel free to cherry-pick if you agree

kwankyu · 2023-11-11T01:47:40Z

I think I have a fix for that in #36498 (87e40a3), please feel free to cherry-pick if you agree

OK. But that may be intentional. Let's see.

mkoeppe · 2023-11-11T06:44:33Z

I think sage_docbuild.ext.multidocs needs to be changed so it does not do HTML things when generating Latex/PDF

kwankyu · 2023-11-11T07:12:40Z

I think sage_docbuild.ext.multidocs needs to be changed so it does not do HTML things when generating Latex/PDF

The reference pdf builder was building reference html doc to create a master index.html for generated pdf docs. This is no problem if html docs are built before pdf docs. But as the pdf workflow only builds pdf docs, this break things.

I fixed it just now. Let's see.

mkoeppe · 2023-11-11T18:11:25Z

PDF build job succeeds, but the HTML build job now fails https://github.com/sagemath/sage/actions/runs/6834646326/job/18587631286?pr=36692#step:10:2680

  [sagemath_doc_html-none]   File "/sage/src/sage_docbuild/__main__.py", line 508, in <module>
  [sagemath_doc_html-none]     sys.exit(main())
  [sagemath_doc_html-none]              ^^^^^^
  [sagemath_doc_html-none]   File "/sage/src/sage_docbuild/__main__.py", line 504, in main
  [sagemath_doc_html-none]     builder()
  [sagemath_doc_html-none]   File "/sage/src/sage_docbuild/builders.py", line 445, in html
  [sagemath_doc_html-none]     shutil.copytree(src, dst)
  [sagemath_doc_html-none]   File "/sage/local/var/lib/sage/venv-python3.11.1/lib/python3.11/shutil.py", line 559, in copytree
  [sagemath_doc_html-none]     with os.scandir(src) as itr:
  [sagemath_doc_html-none]          ^^^^^^^^^^^^^^^
  [sagemath_doc_html-none] FileNotFoundError: [Errno 2] No such file or directory: '/sage/local/share/doc/sage/html/en/website/_static'
  [sagemath_doc_html-none] 
  [sagemath_doc_html-none]     Note: incremental documentation builds sometimes cause spurious
  [sagemath_doc_html-none]     error messages. To be certain that these are real errors, run
  [sagemath_doc_html-none]     "make doc-clean doc-uninstall" first and try again.
  [sagemath_doc_html-none] make[3]: *** [Makefile:32: doc-html--website] Error 1

kwankyu · 2023-11-11T22:57:16Z

Yes. I know.

Before, pdf docs were always built after html docs were built. That is how the code is organized. Now, for CI, we want to build pdf docs separately. This opens the can of worms...

But we are almost there.

mkoeppe · 2023-11-12T01:43:55Z

Looking good now, from a brief look at the PDFs in the generated artifact and the HTML diff.

mkoeppe · 2023-11-12T01:46:08Z

(2) Support .. ONLY:: (introduced by #36495) in generating rst files for sage modules.

Could you elaborate on that? (Here or in the developer's guide)

kwankyu · 2023-11-12T02:09:29Z

In src/doc/en/reference/polynomial_rings/index.rst, there is


Boolean Polynomials
-------------------

.. ONLY:: feature_sage_rings_polynomial_pbori

   .. toctree::
      :maxdepth: 1

      sage/rings/polynomial/pbori/pbori

.. include:: ../footer.txt

.. ONLY:: directive tells sphinx to not process the block. But Sage doc builders in src/sage_docbuild/builders.py does not know this. The reference builder scans the index file to make up the list of sage modules for each of which an rst file is auto-generated into src/doc/reference/polynomial_rings/sage/.... Since the builder does not know how to deal with .. ONLY::, it processes sage/rings/polynomial/pbori/pbori and generates the corresponding rst file. This causes a problem since there is no known item sage/rings/polynomial/pbori/pbori in the index file. I fixed the reference builder process .. ONLY:: directive correctly.

I don't think this explanation needs to go into the developer manual.

mkoeppe · 2023-11-12T02:14:16Z

Thanks for the explanation, and for the fix!

I agree, no need to add to the manual.

mkoeppe · 2023-11-12T02:48:32Z

Ready for review?

kwankyu · 2023-11-12T03:12:18Z

I am testing the last commit on my fork.

Confused as already pushed to develop...

mkoeppe · 2023-11-12T03:40:33Z

Confused as already pushed to develop...

Volker just force-pushed develop, as announced in https://groups.google.com/g/sage-release/c/iCofn2lztjY/m/Ka_T1juZCQAJ; strangely the release tag is still in the old place

kwankyu · 2023-11-12T05:11:10Z

OK. This is good to go. I tried to include pdf docs to the live doc preview but gave up for now.

mkoeppe

LGTM.

kwankyu · 2023-11-12T05:16:15Z

Thanks!

mkoeppe · 2023-11-12T05:16:41Z

Thanks a lot for this work. This is a great step towards #29868

kwankyu · 2023-11-12T09:07:11Z

Sorry, but I found a defect that needs some work.

This is still good to fix the pdf doc workflow. So leave it as blocker.

kwankyu · 2023-11-12T15:05:45Z

Now make doc-pdf correctly builds the pdf docs website if run after make doc-html.

(1) Fixes the issue in sagemath#36614 (comment) by making doc-pdf target separate from doc-html target. (2) Support `.. ONLY::` (introduced by sagemath#36495) in generating rst files for sage modules by the reference builder. (3) Edited the pdf docs website to look consistent and tidy.    ### 📝 Checklist     - [x] The title is concise, informative, and self-explanatory. - [x] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. - [ ] I have created tests covering the changes. - [ ] I have updated the documentation accordingly. ### ⌛ Dependencies   URL: sagemath#36692 Reported by: Kwankyu Lee Reviewer(s): Matthias Köppe

github-actions · 2023-11-13T03:38:34Z

Documentation preview for this PR (built with commit afb9964; changes) is ready! 🎉

Currently live doc preview lacks pdf docs though links to them are visible, as seen https://deploy-livedoc--sagemath-tobias.netlify.app/ We fix the problem. The live doc preview built with this PR is here: https://deploy-livedoc--sagemath.netlify.app/      ### 📝 Checklist     - [x] The title is concise, informative, and self-explanatory. - [x] The description explains in detail what this PR is about. - [x] I have linked a relevant issue or discussion. - [ ] I have created tests covering the changes. - [ ] I have updated the documentation accordingly. ### ⌛ Dependencies  - sagemath#36692  URL: sagemath#36714 Reported by: Kwankyu Lee Reviewer(s): Matthias Köppe

kwankyu changed the title ~~reference-top is built after sub docs~~ Build reference_top after sub docs of reference manual Nov 10, 2023

mkoeppe added c: build c: documentation labels Nov 10, 2023

kwankyu marked this pull request as draft November 11, 2023 01:37

kwankyu marked this pull request as ready for review November 11, 2023 04:26

kwankyu force-pushed the fix-doc-build branch from 4e376a4 to 6308fe6 Compare November 11, 2023 07:08

mkoeppe added this to the sage-10.2 milestone Nov 12, 2023

mkoeppe added the p: blocker / 1 label Nov 12, 2023

vbraun force-pushed the develop branch from 429555a to e349b00 Compare November 12, 2023 02:08

kwankyu added the s: needs review label Nov 12, 2023

Fix pdf doc build

84fb6da

kwankyu force-pushed the fix-doc-build branch from 5bcff9f to 84fb6da Compare November 12, 2023 04:22

kwankyu changed the title ~~Build reference_top after sub docs of reference manual~~ Make doc-pdf separate from making doc-html Nov 12, 2023

kwankyu changed the title ~~Make doc-pdf separate from making doc-html~~ Make doc-pdf separate from doc-html Nov 12, 2023

Revert live doc - no pdfs

907276a

mkoeppe approved these changes Nov 12, 2023

View reviewed changes

mkoeppe added s: positive review and removed s: needs review labels Nov 12, 2023

kwankyu mentioned this pull request Nov 12, 2023

pip-installable packages sagemath-doc-src, sagemath-doc-inventory, sagemath-doc-html, sagemath-doc-pdf #29868

Open

kwankyu added s: needs work and removed s: positive review labels Nov 12, 2023

kwankyu added 2 commits November 12, 2023 20:48

Revive pdf docs index page

8912679

Make pdf links tidy

dc2f4fe

kwankyu added s: positive review and removed s: needs work labels Nov 12, 2023

mkoeppe approved these changes Nov 12, 2023

View reviewed changes

vbraun force-pushed the develop branch from 883e05f to e349b00 Compare November 12, 2023 16:25

Merge branch 'develop' into fix-doc-build

afb9964

kwankyu mentioned this pull request Nov 13, 2023

Deploy live doc preview with pdf docs #36714

Merged

5 tasks

vbraun merged commit 613775f into sagemath:develop Nov 14, 2023
15 of 17 checks passed

github-actions bot removed the s: positive review label Nov 14, 2023

kwankyu mentioned this pull request Nov 28, 2023

pkgs/sagemath-doc-{html,pdf} #36730

Draft

5 tasks

kwankyu deleted the fix-doc-build branch December 13, 2023 12:00

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Make doc-pdf separate from doc-html #36692

Make doc-pdf separate from doc-html #36692

kwankyu commented Nov 10, 2023 •

edited

Loading

mkoeppe commented Nov 10, 2023

mkoeppe commented Nov 10, 2023 •

edited

Loading

kwankyu commented Nov 11, 2023

mkoeppe commented Nov 11, 2023 •

edited

Loading

kwankyu commented Nov 11, 2023 •

edited

Loading

mkoeppe commented Nov 11, 2023

kwankyu commented Nov 11, 2023 •

edited

Loading

mkoeppe commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023 •

edited

Loading

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023

mkoeppe left a comment

kwankyu commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023

kwankyu commented Nov 12, 2023

github-actions bot commented Nov 13, 2023

Make doc-pdf separate from doc-html #36692

Make doc-pdf separate from doc-html #36692

Conversation

kwankyu commented Nov 10, 2023 • edited Loading

📝 Checklist

⌛ Dependencies

mkoeppe commented Nov 10, 2023

mkoeppe commented Nov 10, 2023 • edited Loading

kwankyu commented Nov 11, 2023

mkoeppe commented Nov 11, 2023 • edited Loading

kwankyu commented Nov 11, 2023 • edited Loading

mkoeppe commented Nov 11, 2023

kwankyu commented Nov 11, 2023 • edited Loading

mkoeppe commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023 • edited Loading

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023

mkoeppe left a comment

Choose a reason for hiding this comment

kwankyu commented Nov 12, 2023

mkoeppe commented Nov 12, 2023

kwankyu commented Nov 12, 2023

kwankyu commented Nov 12, 2023

github-actions bot commented Nov 13, 2023

kwankyu commented Nov 10, 2023 •

edited

Loading

mkoeppe commented Nov 10, 2023 •

edited

Loading

mkoeppe commented Nov 11, 2023 •

edited

Loading

kwankyu commented Nov 11, 2023 •

edited

Loading

kwankyu commented Nov 11, 2023 •

edited

Loading

kwankyu commented Nov 12, 2023 •

edited

Loading