From 84fb6dac85ffbab02d69c1594a9ae4a2bccf6c84 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 12 Nov 2023 13:22:23 +0900 Subject: [PATCH 1/4] Fix pdf doc build --- .github/workflows/doc-build.yml | 2 +- src/doc/Makefile | 14 +++---- src/doc/en/reference/references/index.rst | 7 ++++ .../combinat/species/generating_series.py | 11 +----- src/sage/rings/lazy_series.py | 2 +- src/sage_docbuild/builders.py | 38 +++++++++++++++---- src/sage_docbuild/conf.py | 2 +- 7 files changed, 49 insertions(+), 27 deletions(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 3660ff3a947..7d87c9ed4c5 100644 --- a/.github/workflows/doc-build.yml +++ b/.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 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 d9f406d055d..50b4ad0fead 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/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..c79b61c1506 100644 --- a/src/sage_docbuild/builders.py +++ b/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, '.') diff --git a/src/sage_docbuild/conf.py b/src/sage_docbuild/conf.py index 93333c2509d..8602016d042 100644 --- a/src/sage_docbuild/conf.py +++ b/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 From 907276a710c25df6aea8a09dc6c8f8621f7eda5e Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 12 Nov 2023 13:47:22 +0900 Subject: [PATCH 2/4] Revert live doc - no pdfs --- .github/workflows/doc-build.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/doc-build.yml b/.github/workflows/doc-build.yml index 7d87c9ed4c5..3660ff3a947 100644 --- a/.github/workflows/doc-build.yml +++ b/.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 doc-html && make doc-pdf + ./config.status && make sagemath_doc_html-no-deps working-directory: ./worktree-image env: MAKE: make -j2 --output-sync=recurse From 8912679e891e4ea8e8383a2110df66738b7c80c9 Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 12 Nov 2023 19:57:29 +0900 Subject: [PATCH 3/4] Revive pdf docs index page --- src/doc/en/website/root_index.html | 2 +- src/doc/en/website/templates/index.html | 54 ++++++++++---------- src/doc/en/website/templates/index_furo.html | 54 ++++++++++---------- src/sage_docbuild/builders.py | 33 ++++++++++-- 4 files changed, 83 insertions(+), 60 deletions(-) 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_docbuild/builders.py b/src/sage_docbuild/builders.py index c79b61c1506..b113724789b 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 @@ -643,7 +666,7 @@ def pdf(self): 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: @@ -707,7 +730,7 @@ def pdf(self): rst = re.sub(r'`([^<\n]*)\s+<(.*)>`_', r'\1', rst) rst = re.sub(r':doc:`([^<]*?)\s+<(.*)/index>`', - r'\1 ', rst) + r' \1', rst) # Body: add paragraph

markup. start = rst.rfind('*\n') + 1 end = rst.find('\nUser Interfaces') @@ -725,7 +748,7 @@ def pdf(self): rst_toc = re.sub(r'\n([A-Z][a-zA-Z, ]*)\n[-]*\n', r'\n\n\n

\1

\n\n
    \n', rst_toc) # now write the file. - with open(os.path.join(output_dir, 'index.html'), 'w') as new_index: + with open(os.path.join(output_dir, 'index-pdf.html'), 'w') as new_index: new_index.write(html[:html_end_preamble]) new_index.write('

    Sage Reference Manual (PDF version)

    ') new_index.write(rst_body) From dc2f4fe34e4a03c62817d22198ae8f89313f33ab Mon Sep 17 00:00:00 2001 From: Kwankyu Lee Date: Sun, 12 Nov 2023 23:59:29 +0900 Subject: [PATCH 4/4] Make pdf links tidy --- src/sage_docbuild/builders.py | 19 ++----------------- 1 file changed, 2 insertions(+), 17 deletions(-) diff --git a/src/sage_docbuild/builders.py b/src/sage_docbuild/builders.py index b113724789b..63aa1145154 100644 --- a/src/sage_docbuild/builders.py +++ b/src/sage_docbuild/builders.py @@ -690,9 +690,6 @@ def pdf(self): 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'