Merge branch 'p/deploy-live-doc-with-pdfs' into ci_docbuild_explicit_docker_exec

Author: Matthias Koeppe

.github/workflows/doc-build.yml

@@ -173,14 +173,15 @@ jobs:
         if: (success() || failure()) && steps.copy.outcome == 'success' && github.repository == 'sagemath/sage' && github.ref == 'refs/heads/develop'
         run: |
           export MAKE="make -j2 --output-sync=recurse" SAGE_NUM_THREADS=2
+          export PATH="build/bin:$PATH"
+          eval $(sage-print-system-package-command auto update)
+          eval $(sage-print-system-package-command auto --yes --no-install-recommends install zip)
+          eval $(sage-print-system-package-command auto --spkg --yes --no-install-recommends install git texlive)
           export SAGE_USE_CDNS=yes
           export SAGE_LIVE_DOC=yes
           export SAGE_JUPYTER_SERVER=binder:sagemath/sage-binder-env/dev
           make doc-clean doc-uninstall
-          ./config.status && make sagemath_doc_html-no-deps
-        env:
-          MAKE: make -j2 --output-sync=recurse
-          SAGE_NUM_THREADS: 2
+          ./config.status && make sagemath_doc_html-no-deps sagemath_doc_pdf-no-deps
         shell: sh .ci/docker-exec-script.sh BUILD ./worktree-image {0}
 
       - name: Copy live doc
@@ -189,6 +190,7 @@ jobs:
         run: |
           mkdir -p ./livedoc
           cp -r -L /sage/local/share/doc/sage/html ./livedoc
+          cp -r -L /sage/local/share/doc/sage/pdf ./livedoc
           cp  /sage/local/share/doc/sage/index.html ./livedoc
           zip -r livedoc.zip livedoc
         shell: sh .ci/docker-exec-script.sh BUILD . {0}

src/doc/Makefile

@@ -46,14 +46,17 @@ doc-inventory-reference: doc-src
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-inventory--reference_top
 endif
 
-# reference manual, html
-doc-html-reference: doc-inventory-reference
+# sub docs of reference manual, html
+doc-html-reference-sub: doc-inventory-reference
 	$(eval DOCS = $(shell sage --docbuild --all-documents reference))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
 	$(eval BIBLIO = $(firstword $(DOCS)))
 	$(eval OTHER_DOCS = $(wordlist 2, 100, $(DOCS)))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-html--$(subst /,-,$(BIBLIO))
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(OTHER_DOCS), doc-html--$(subst /,-,$(doc)))
+
+# reference manual, html; reference_top is built after sub docs
+doc-html-reference: doc-html-reference-sub
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-html--reference_top
 
 # other documentation, html
@@ -79,16 +82,13 @@ doc-pdf-reference: doc-inventory-reference
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" doc-pdf--reference_top
 
 # other documentation, pdf
-doc-pdf-other: doc-html-reference
+doc-pdf-other: doc-pdf-reference
 	$(eval DOCS = $(shell sage --docbuild --all-documents all))
 	@if [ -z "$(DOCS)" ]; then echo "Error: 'sage --docbuild --all-documents' failed"; exit 1; fi
 	$(MAKE) SAGE_DOCBUILD_OPTS="$(SAGE_DOCBUILD_OPTS) --no-prune-empty-dirs" $(foreach doc, $(wordlist 2, 100, $(DOCS)), doc-pdf--$(subst /,-,$(doc)))
 
-# website with pdf links
-doc-pdf-website:
-	sage --docbuild website html $(SAGE_DOCBUILD_OPTS)
+doc-pdf: doc-pdf-reference doc-pdf-other
 
-doc-pdf: doc-pdf-reference doc-pdf-other doc-pdf-website
 
 .PHONY: all clean \
 	doc-src \

src/doc/common/static/custom-furo.css

@@ -11,3 +11,13 @@ body[data-theme="dark"] div.highlight {
   background: #383838;
 }
 
+/* Copied the style for a.pdf from website/templates/index_furo.html */
+
+a.pdf {
+  margin-right: 0.5em;
+}
+
+a.pdf:hover {
+  text-decoration: none;
+}
+

src/doc/en/reference/references/index.rst

@@ -960,6 +960,13 @@ REFERENCES:
 .. [BL2003] \S. Brlek, A. Ladouceur, A note on differentiable palindromes,
             Theoret. Comput. Sci. 302 (2003) 167--178.
 
+.. [BLL1998] \F. Bergeron, G. Labelle, and P. Leroux.
+             "Combinatorial species and tree-like structures".
+             Encyclopedia of Mathematics and its Applications, vol. 67, Cambridge Univ. Press. 1998.
+
+.. [BLL2008] François Bergeron, Gilbert Labelle, and Pierre Leroux.
+             "Introduction to the Theory of Species of Structures", March 14, 2008.
+
 .. [BraLea2008] \C. Bracken and Gregor Leander: *New families of functions
              with differential uniformity of 4*, Proceedings of the Conference
              BFCA, Copenhagen, 2008.

src/doc/en/website/root_index.html

@@ -118,7 +118,7 @@ <h1>Sage Documentation</h1>
 <div class='entry lang-en'><a href='pdf/en/prep/prep_tutorials.pdf'>PREP Tutorials</a></div>
 <div class='entry lang-en'><a href='pdf/en/constructions/constructions.pdf'>Constructions</a></div>
 <div class='entry lang-en'><a href='pdf/en/faq/faq.pdf'>FAQ</a></div>
-<div class='entry lang-en'><a href='pdf/en/reference/index.html'>Reference Manual</a></div>
+<div class='entry lang-en'><a href='html/en/reference/index-pdf.html'>Reference Manual</a></div>
 <div class='entry lang-en'><a href='pdf/en/installation/installation.pdf'>Installation Guide</a></div>
 <div class='entry lang-en'><a href='pdf/en/developer/developer.pdf'>Developer Guide</a></div>
 </div></div>

src/doc/en/website/templates/index.html

@@ -44,12 +44,12 @@ <h2>
    <tr valign="top">
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="a_tour_of_sage/index.html">
-          A Tour of Sage
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/a_tour_of_sage/a_tour_of_sage.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="a_tour_of_sage/index.html">
+          A Tour of Sage
+        </a>
         <br>
         <span class="linkdescr">
           This is a tour of Sage that closely follows the tour of
@@ -60,12 +60,12 @@ <h2>
     </td>
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="prep/index.html">
-          PREP Tutorials
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/prep/prep_tutorials.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="prep/index.html">
+          PREP Tutorials
+        </a>
         <br>
         <span class="linkdescr">
           This set of tutorials takes the reader from very minimal
@@ -80,12 +80,12 @@ <h2>
   <tr valign="top">
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="tutorial/index.html">
-          Tutorial
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/tutorial/sage_tutorial.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="tutorial/index.html">
+          Tutorial
+        </a>
         <br>
         <span class="linkdescr">
           This tutorial is the best way to become familiar with Sage
@@ -95,12 +95,12 @@ <h2>
     </td>
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="constructions/index.html">
-          Constructions
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/constructions/constructions.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="constructions/index.html">
+          Constructions
+        </a>
         <br>
         <span class="linkdescr">
           This document collects answers to some questions along the line "How
@@ -113,12 +113,12 @@ <h2>
   <tr valign="top">
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="thematic_tutorials/index.html">
-          Thematic Tutorials
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/thematic_tutorials/thematic_tutorials.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="thematic_tutorials/index.html">
+          Thematic Tutorials
+        </a>
         <br>
         <span class="linkdescr">
           A collection of in-depth tutorials on specific topics. These
@@ -133,12 +133,12 @@ <h2>
     </td>
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="faq/index.html">
-          FAQ
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/faq/faq.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="faq/index.html">
+          FAQ
+        </a>
         <br>
         <span class="linkdescr">
           A collection of frequently asked questions, together with
@@ -158,12 +158,12 @@ <h2>
   <tr valign="top">
     <td width="50%">
       <p class="biglink">
+        <a title="Link to PDF" class="pdf" href="reference/index-pdf.html">
+          <img class="icon" src="_static/pdf.png"></img>
+        </a>
         <a class="biglink" href="reference/index.html">
           Reference Manual
         </a>
-        <a title="Link to PDF" class="pdf" href="../../pdf/en/reference/index.html">
-          <img class="icon" src="_static/pdf.png"></img>
-        </a>
         <br>
         <span class="linkdescr">
           This is the reference manual for the Sage mathematics
@@ -189,12 +189,12 @@ <h2>
   <tr valign="top">
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="installation/index.html">
-          Installation Guide
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/installation/installation.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="installation/index.html">
+          Installation Guide
+        </a>
         <br>
         <span class="linkdescr">
           A guide on how to install Sage. You can install a Sage
@@ -206,12 +206,12 @@ <h2>
     </td>
     <td width="50%">
       <p class="biglink">
-        <a class="biglink" href="developer/index.html">
-          Developer Guide
-        </a>
         <a title="Download PDF" class="pdf" href="../../pdf/en/developer/developer.pdf">
           <img class="icon" src="_static/pdf.png"></img>
         </a>
+        <a class="biglink" href="developer/index.html">
+          Developer Guide
+        </a>
         <br>
         <span class="linkdescr">
           This document describes guidelines and policies regarding