-
-
Notifications
You must be signed in to change notification settings - Fork 491
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Reimplement parallel docbuild using make #31948
Comments
comment:1
I'm not quite sure how to go about this. I tried this: diff --git a/build/make/Makefile.in b/build/make/Makefile.in
index fb3a6ed5bc..4581dc3226 100644
--- a/build/make/Makefile.in
+++ b/build/make/Makefile.in
@@ -335,7 +335,12 @@ DOC_DEPENDENCIES = sagelib sage_docbuild $(inst_sphinx) \
$(inst_ipykernel) $(inst_jupyter_client) $(inst_conway_polynomials) \
$(inst_tachyon) $(inst_jmol) $(inst_thebe) $(inst_ipywidgets)
-doc: doc-html
+doc: doc-new
+
+doc-new: $(DOC_DEPENDENCIES)
+ for doc in $(shell cd $(SAGE_ROOT) && ./sage --docbuild --all-documents all); do \
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links $$doc html $(SAGE_DOCBUILD_OPTS)" logs/dochtml.log; \
+ done
doc-html: $(DOC_DEPENDENCIES)
$(AM_V_at)cd ../.. && sage-logger -p './sage --docbuild --no-pdf-links all html $(SAGE_DOCBUILD_OPTS)' logs/dochtml.log and it seems to build the documentation, but it doesn't do it in parallel, I think because we've turned off parallel processing for recursive calls to make earlier in the file. If it did work, this approach would need a little tinkering: we should build the reference manual first, then everything else. A separate question: why do we use |
comment:2
And if we really want to pull all of the parallel building out of the current system, then we should build the pieces of the reference manual separately in the |
comment:3
Here is my current attempt, which doesn't quite work: diff --git a/build/make/Makefile.in b/build/make/Makefile.in
index fb3a6ed5bc..c199de440d 100644
--- a/build/make/Makefile.in
+++ b/build/make/Makefile.in
@@ -335,7 +335,27 @@ DOC_DEPENDENCIES = sagelib sage_docbuild $(inst_sphinx) \
$(inst_ipykernel) $(inst_jupyter_client) $(inst_conway_polynomials) \
$(inst_tachyon) $(inst_jmol) $(inst_thebe) $(inst_ipywidgets)
-doc: doc-html
+doc: doc-references doc-other
+
+doc-references: $(DOC_DEPENDENCIES)
+ $(eval DOCS = $(shell cd $(SAGE_ROOT) && ./sage --docbuild --all-documents reference))
+ $(eval biblio = $(firstword $(DOCS)))
+ $(eval other_docs = $(wordlist 2, 100, $(DOCS)))
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links $(biblio) inventory $(SAGE_DOCBUILD_OPTS)" logs/docs-reference-html.log; \
+ for doc in $(other_docs); do \
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links $$doc inventory $(SAGE_DOCBUILD_OPTS)" logs/docs-reference-html.log; \
+ done
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links reference inventory $(SAGE_DOCBUILD_OPTS)" logs/docs-reference-html.log; \
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links $(biblio) html $(SAGE_DOCBUILD_OPTS)" logs/docs-reference-html.log; \
+ for doc in $(other_docs); do \
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links $$doc html $(SAGE_DOCBUILD_OPTS)" logs/docs-reference-html.log; \
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links reference html $(SAGE_DOCBUILD_OPTS)" logs/docs-reference-html.log; \
+ done
+
+doc-other: $(DOC_DEPENDENCIES) doc-references
+ for doc in $(wordlist 2, 100, $(shell cd $(SAGE_ROOT) && ./sage --docbuild --all-documents all)); do \
+ $(AM_V_at)cd $(SAGE_ROOT) && sage-logger -p "./sage --docbuild --no-pdf-links $$doc html $(SAGE_DOCBUILD_OPTS)" logs/docs-other-html.log; \
+ done
doc-html: $(DOC_DEPENDENCIES)
$(AM_V_at)cd ../.. && sage-logger -p './sage --docbuild --no-pdf-links all html $(SAGE_DOCBUILD_OPTS)' logs/dochtml.log
diff --git a/src/sage_docbuild/__init__.py b/src/sage_docbuild/__init__.py
index 79005b903a..a3caa8a92d 100644
--- a/src/sage_docbuild/__init__.py
+++ b/src/sage_docbuild/__init__.py
@@ -116,7 +116,7 @@ def builder_helper(type):
# WEBSITESPHINXOPTS is either empty or " -A hide_pdf_links=1 "
options += WEBSITESPHINXOPTS
- if kwds.get('use_multidoc_inventory', True):
+ if kwds.get('use_multidoc_inventory', True) and type != 'inventory':
options += ' -D multidoc_first_pass=0'
else:
options += ' -D multidoc_first_pass=1' Several problems:
|
comment:4
To get |
comment:5
I don't see how to do anything like that unless we hardcode the list of documents: we can't run |
comment:6
Or write a standalone script to construct the document list. |
comment:7
Could you push your current version to the ticket please? |
Commit: |
comment:9
Here it is. New commits:
|
Changed branch from u/jhpalmieri/parallel-docbuild-with-make to u/mkoeppe/parallel-docbuild-with-make |
comment:11
Here's a solution using recursive make invocation New commits:
|
comment:12
This doesn't work for me, unfortunately. If I do
With the following change, the documentation builds: diff --git a/build/make/Makefile.in b/build/make/Makefile.in
index 339497fd17..12b4e56b20 100644
--- a/build/make/Makefile.in
+++ b/build/make/Makefile.in
@@ -349,11 +349,7 @@ doc-references: $(DOC_DEPENDENCIES)
$(eval DOCS = $(shell cd $(SAGE_ROOT) && ./sage --docbuild --all-documents reference))
$(eval biblio = $(firstword $(DOCS)))
$(eval other_docs = $(wordlist 2, 100, $(DOCS)))
- +$(MAKE_REC) doc-inventory-$(subst /,-,$(biblio))
- +$(MAKE_REC) $(foreach doc, $(other_docs), doc-inventory-$(subst /,-,$(doc)))
+$(MAKE_REC) doc-inventory-reference
- +$(MAKE_REC) doc-html-$(subst /,-,$(biblio))
- +$(MAKE_REC) $(foreach doc, $(other_docs), doc-html-$(subst /,-,$(doc)))
+$(MAKE_REC) doc-html-reference
doc-other: $(DOC_DEPENDENCIES) doc-references This is a hybrid model, using the old parallel building methods for the reference manual. The inventory build is fine, but I get some strange warnings during the html build:
I don't know what |
comment:13
Replying to @jhpalmieri:
Looks like something forgot to create the directory in which this .rst file is to be created |
comment:14
I was able to reproduce an error of this form as well. |
comment:15
If you do |
comment:16
I'll add an option to turn it off |
Branch pushed to git repo; I updated commit sha1. New commits:
|
Author: John Palmieri, Matthias Koeppe |
comment:19
I still see
for (I think) every piece of the reference manual. Any ideas about this? Edit: the manual seems to build correctly, regardless. |
comment:20
No idea about this error. I don't see it here. I suppose you could try to run the docbuild for a document in |
comment:22
I haven't tried One more task: the reference manual is built twice: the line
needs to be replaced with something that just builds the top-level ref manual indices, and similarly for the html build. I may be able to work on this later, but please go ahead if you want to take a stab at it. |
comment:23
If it shows up again, perhaps #31005 (Add traceback information to exceptions during docbuild) can help to diagnose it |
comment:24
OK, I see |
Branch pushed to git repo; I updated commit sha1. This was a forced push. New commits:
|
comment:73
Okay, I think I'm done tinkering now. |
comment:75
Looks good and seems to work well. Positive review from my side |
comment:76
Dima, any comments? I'm happy with Matthias' contributions. |
Changed reviewer from Matthias Koeppe, ... to Matthias Koeppe, John Palmieri, ... |
Branch pushed to git repo; I updated commit sha1. New commits:
|
comment:79
looks good, thanks! |
Changed reviewer from Matthias Koeppe, John Palmieri, ... to Matthias Koeppe, John Palmieri, Dima Pasechnik |
comment:80
Great, thank you! |
This comment has been minimized.
This comment has been minimized.
Changed branch from u/jhpalmieri/parallel-docbuild-with-make to |
Changed commit from |
comment:83
Previously |
comment:84
I've opened #32043 for this |
comment:85
I am seeing a race condition, sphinx may race
See e.g. https://github.com/sagemath/sagetrac-mirror/runs/3104375540 It's of course not totally surprising that several processes may try to, say, create the same directory. Perhaps the relevant part of the builder should be launched with this specific error being ignored? |
comment:86
It's strange because that doesn't look like part of the docbuild process that's done in parallel with anything else: it looks like the main reference page, built after the other parts of the reference manual. How reliably can you reproduce this? I think this part of the process (copying static files) is controlled by Sphinx, not by Sage or its modifications to Sphinx, for what that's worth. |
comment:87
Replying to @dimpase:
new ticket please? |
Based on #31353 (
sage --docbuild
: Add options to list all documents), we can remove the issues with parallel (#31344) and serial (#31936) docbuild by restructuring the docbuild usingmake
.Blocker because it solves blocker issue #31936.
CC: @dimpase
Component: build
Author: John Palmieri, Matthias Koeppe
Branch:
53f260c
Reviewer: Matthias Koeppe, John Palmieri, Dima Pasechnik
Issue created by migration from https://trac.sagemath.org/ticket/31948
The text was updated successfully, but these errors were encountered: