Fix pdf doc build

Author: kwankyu

.github/workflows/doc-build.yml

@@ -206,7 +206,7 @@ jobs:
           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
+          ./config.status && make doc-html && make doc-pdf
         working-directory: ./worktree-image
         env:
           MAKE: make -j2 --output-sync=recurse

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

src/sage_docbuild/builders.py

@@ -637,17 +637,21 @@ def pdf(self):
         """
         super().pdf()
 
-        # we need to build master index file which lists all
-        # of the PDF file.  So we create an html file, based on
-        # the file index.html from the "reference_top" target.
-
-        # First build the top reference page. This only takes a few seconds.
-        getattr(get_builder('reference_top'), 'html')()
+        # We want to build master index file which lists all of the PDF file.
+        # We modify the file index.html from the "reference_top" target, if it
+        # exists. Otherwise, we are done.
 
         from sage.env import SAGE_DOC
         reference_dir = os.path.join(SAGE_DOC, 'html', 'en', 'reference')
         output_dir = self._output_dir('pdf')
 
+        # Check if the top reference index.html exists.
+        try:
+            with open(os.path.join(reference_dir, 'index.html')) as f:
+                html = f.read()
+        except FileNotFoundError:
+            return
+
         # Install in output_dir a symlink to the directory containing static files.
         # Prefer relative path for symlinks.
         relpath = os.path.relpath(reference_dir, output_dir)
@@ -657,8 +661,6 @@ def pdf(self):
             pass
 
         # Now modify top reference index.html page and write it to output_dir.
-        with open(os.path.join(reference_dir, 'index.html')) as f:
-            html = f.read()
         html_output_dir = os.path.dirname(reference_dir)
 
         # Fix links in navigation bar
@@ -1051,13 +1053,33 @@ def get_modules(self, filename):
         Given a filename for a reST file, return an iterator for
         all of the autogenerated reST files that it includes.
         """
+        from sage.features.all import all_features
+
         # Create the regular expression used to detect an autogenerated file
         auto_re = re.compile(r'^\s*(..\/)*(sage(_docbuild)?\/[\w\/]*)\s*$')
 
         # Read the lines
         with open(filename) as f:
             lines = f.readlines()
+
+        skip = False
         for line in lines:
+            if skip:
+                if not line.strip() or line.count(' ', 0) >= indent:
+                    continue
+                skip = False
+            elif line.lstrip().lower().startswith('.. only::'):
+                try:
+                    tag_name = line[line.index('feature_') + 8:].strip()
+                    for feature in all_features():
+                        if tag_name == feature.name.replace('.', '_'):
+                            break
+                    else:
+                        skip = True
+                        indent = line.index('.. ') + 3
+                        continue
+                except ValueError:
+                    pass
             match = auto_re.match(line)
             if match:
                 yield match.group(2).replace(os.path.sep, '.')

src/sage_docbuild/conf.py

@@ -296,7 +296,7 @@ def set_intersphinx_mappings(app, config):
     intersphinx.normalize_intersphinx_mapping(app, config)
 
 
-# By default document are not master.
+# By default document is master.
 multidocs_is_master = True
 
 # https://sphinx-copybutton.readthedocs.io/en/latest/use.html