gh-36692: Make doc-pdf separate from doc-html
    
<!-- ^^^^^
Please provide a concise, informative and self-explanatory title.
Don't put issue numbers in there, do this in the PR body below.
For example, instead of "Fixes #1234" use "Introduce new method to
calculate 1+1"
-->
<!-- Describe your changes here in detail -->

(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.

<!-- Why is this change required? What problem does it solve? -->
<!-- If this PR resolves an open issue, please link to it here. For
example "Fixes #12345". -->
<!-- If your change requires a documentation PR, please link it
appropriately. -->

### 📝 Checklist

<!-- Put an `x` in all the boxes that apply. -->
<!-- If your change requires a documentation PR, please link it
appropriately -->
<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
<!-- Feel free to remove irrelevant items. -->

- [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

<!-- List all open PRs that this PR logically depends on
- #12345: short description why this is a dependency
- #34567: ...
-->

<!-- If you're unsure about any of these, don't hesitate to ask. We're
here to help! -->
    
URL: #36692
Reported by: Kwankyu Lee
Reviewer(s): Matthias Köppe

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/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

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

@@ -41,12 +41,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">
           A one page introduction to Sage as a handy calculator.
@@ -55,12 +55,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
@@ -75,12 +75,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">
           The best way to become familiar with Sage
@@ -90,12 +90,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
@@ -108,12 +108,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
@@ -128,12 +128,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
@@ -153,12 +153,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
@@ -184,12 +184,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
@@ -201,12 +201,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

src/sage/combinat/species/generating_series.py

@@ -30,13 +30,6 @@
     sage: s[3]                                                                          # optional - sage.modules
     p[1, 1, 1] + p[2, 1]
 
-REFERENCES:
-
-.. [BLL] \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.
-.. [BLL-Intro] François Bergeron, Gilbert Labelle, and Pierre Leroux.
-   "Introduction to the Theory of Species of Structures", March 14, 2008.
 """
 
 # ****************************************************************************
@@ -217,7 +210,7 @@ def functorial_composition(self, y):
 
         REFERENCES:
 
-        - Section 2.2 of [BLL]_.
+        - Section 2.2 of [BLL1998]_.
 
         EXAMPLES::
 
@@ -651,7 +644,7 @@ def LogarithmCycleIndexSeries(R=QQ):
     Return the cycle index series of the virtual species `\Omega`, the
     compositional inverse of the species `E^{+}` of nonempty sets.
 
-    The notion of virtual species is treated thoroughly in [BLL]_.
+    The notion of virtual species is treated thoroughly in [BLL1998]_.
     The specific algorithm used here to compute the cycle index of
     `\Omega` is found in [Labelle2008]_.
 

src/sage/rings/lazy_series.py

@@ -6219,7 +6219,7 @@ def functorial_composition(self, *args):
         whose labels are the set of all `G`-structures on `A`.
 
         The Frobenius character (or cycle index series) of `F \Box G`
-        can be computed as follows, see section 2.2 of [BLL]_):
+        can be computed as follows, see section 2.2 of [BLL1998]_):
 
         .. MATH::