diff --git a/src/doc/Makefile b/src/doc/Makefile index 2f76dfb9cb4..912eb5cb0e9 100644 --- a/src/doc/Makefile +++ b/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 \ diff --git a/src/doc/en/reference/references/index.rst b/src/doc/en/reference/references/index.rst index 697c50a6bcf..fa67dade3ab 100644 --- a/src/doc/en/reference/references/index.rst +++ b/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. diff --git a/src/doc/en/website/root_index.html b/src/doc/en/website/root_index.html index 21a6086ed72..c3d25ff495b 100644 --- a/src/doc/en/website/root_index.html +++ b/src/doc/en/website/root_index.html @@ -118,7 +118,7 @@

Sage Documentation

PREP Tutorials
Constructions
FAQ
-
Reference Manual
+
Reference Manual
Installation Guide
Developer Guide
diff --git a/src/doc/en/website/templates/index.html b/src/doc/en/website/templates/index.html index c63d109b4dc..cad4cbc287a 100644 --- a/src/doc/en/website/templates/index.html +++ b/src/doc/en/website/templates/index.html @@ -44,12 +44,12 @@

- - A Tour of Sage - + + A Tour of Sage +
This is a tour of Sage that closely follows the tour of @@ -60,12 +60,12 @@

- - PREP Tutorials - + + PREP Tutorials +
This set of tutorials takes the reader from very minimal @@ -80,12 +80,12 @@

- - Tutorial - + + Tutorial +
This tutorial is the best way to become familiar with Sage @@ -95,12 +95,12 @@

- - Constructions - + + Constructions +
This document collects answers to some questions along the line "How @@ -113,12 +113,12 @@

- - Thematic Tutorials - + + Thematic Tutorials +
A collection of in-depth tutorials on specific topics. These @@ -133,12 +133,12 @@

- - FAQ - + + FAQ +
A collection of frequently asked questions, together with @@ -158,12 +158,12 @@

+ + + Reference Manual - - -
This is the reference manual for the Sage mathematics @@ -189,12 +189,12 @@

- - Installation Guide - + + Installation Guide +
A guide on how to install Sage. You can install a Sage @@ -206,12 +206,12 @@

- - Developer Guide - + + Developer Guide +
This document describes guidelines and policies regarding diff --git a/src/doc/en/website/templates/index_furo.html b/src/doc/en/website/templates/index_furo.html index 922068b9b52..1dca6907c93 100644 --- a/src/doc/en/website/templates/index_furo.html +++ b/src/doc/en/website/templates/index_furo.html @@ -41,12 +41,12 @@

- - A Tour of Sage - + + A Tour of Sage +
A one page introduction to Sage as a handy calculator. @@ -55,12 +55,12 @@

- - PREP Tutorials - + + PREP Tutorials +
This set of tutorials takes the reader from very minimal @@ -75,12 +75,12 @@

- - Tutorial - + + Tutorial +
The best way to become familiar with Sage @@ -90,12 +90,12 @@

- - Constructions - + + Constructions +
This document collects answers to some questions along the line "How @@ -108,12 +108,12 @@

- - Thematic Tutorials - + + Thematic Tutorials +
A collection of in-depth tutorials on specific topics. These @@ -128,12 +128,12 @@

- - FAQ - + + FAQ +
A collection of frequently asked questions, together with @@ -153,12 +153,12 @@

+ + + Reference Manual - - -
This is the reference manual for the Sage mathematics @@ -184,12 +184,12 @@

- - Installation Guide - + + Installation Guide +
A guide on how to install Sage. You can install a Sage @@ -201,12 +201,12 @@

- - Developer Guide - + + Developer Guide +
This document describes guidelines and policies regarding diff --git a/src/sage/combinat/species/generating_series.py b/src/sage/combinat/species/generating_series.py index e7f7c8ee978..dca117a9971 100644 --- a/src/sage/combinat/species/generating_series.py +++ b/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]_. diff --git a/src/sage/rings/lazy_series.py b/src/sage/rings/lazy_series.py index 8086e15f9ef..5fdfb64cea4 100644 --- a/src/sage/rings/lazy_series.py +++ b/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:: diff --git a/src/sage_docbuild/builders.py b/src/sage_docbuild/builders.py index 323c9247252..63aa1145154 100644 --- a/src/sage_docbuild/builders.py +++ b/src/sage_docbuild/builders.py @@ -431,11 +431,17 @@ class WebsiteBuilder(DocBuilder): def html(self): """ After we have finished building the website index page, we copy - everything one directory up. + everything one directory up, that is, to the base diectory ``html/en``. In addition, an index file is installed into the root doc directory. + + Thus we have three index.html files: + + html/en/website/index.html (not used) + html/en/index.html (base directory) + index.html (root doc directory) """ - DocBuilder.html(self) + super().html() html_output_dir = self._output_dir('html') for f in os.listdir(html_output_dir): src = os.path.join(html_output_dir, f) @@ -450,6 +456,23 @@ def html(self): shutil.copy2(os.path.join(SAGE_DOC_SRC, self.lang, 'website', 'root_index.html'), root_index_file) + def pdf(self): + """ + Build the website hosting pdf docs. + """ + super().pdf() + + # If the website exists, update it. + + from sage.env import SAGE_DOC + website_dir = os.path.join(SAGE_DOC, 'html', 'en', 'website') + + if os.path.exists(os.path.join(website_dir, 'index.html')): + # Rebuild WITHOUT --no-pdf-links, which is translated to + # "-A hide_pdf_links=1" Sphinx argument. Thus effectively + # the index page SHOWS links to pdf docs. + self.html() + def clean(self): """ When we clean the output for the website index, we need to @@ -637,16 +660,20 @@ 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') + output_dir = self._output_dir('html') + + # 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. @@ -657,17 +684,12 @@ 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 html = re.sub(r'Sage(.*)Documentation', r'Sage\2Documentation', html) - html = re.sub(r'Reference Manual', - r'Reference Manual (PDF version)', - html) html = re.sub(r'

  • ', r'