Move handling of "sage --docbuild" back to src/bin/sage
Closed this issue · 20 comments
(from #33650 comment:32)
It was moved in #29111 to build/bin/sage-site, but it does have some (limited - #30475) functionality for users.
sage-docbuild would be declared as an install-requires of sagemath-standard. #29941 also declares it as an extras-require of sagemath-environment.
CC: @jhpalmieri @collares @kiwifb @kwankyu
Component: scripts
Author: Kwankyu Lee
Branch/Commit: fc9b96f
Reviewer: Matthias Koeppe
Issue created by migration from https://trac.sagemath.org/ticket/33795
Description changed:
---
+++
@@ -1,3 +1,5 @@
+(from [#33650 comment:32](https://github.com/sagemath/sage/issues/33650#comment:32))
+
It was moved in #29111 to `build/bin/sage-site`, but it does have some (limited) functionality for users.
Description changed:
---
+++
@@ -2,4 +2,5 @@
It was moved in #29111 to `build/bin/sage-site`, but it does have some (limited) functionality for users.
+**sage-docbuild** would be declared as an `extras-require` of **sagemath-standard**.
Description changed:
---
+++
@@ -1,6 +1,6 @@
(from [#33650 comment:32](https://github.com/sagemath/sage/issues/33650#comment:32))
-It was moved in #29111 to `build/bin/sage-site`, but it does have some (limited) functionality for users.
+It was moved in #29111 to `build/bin/sage-site`, but it does have some (limited - #30475) functionality for users.
**sage-docbuild** would be declared as an `extras-require` of **sagemath-standard**.
I personally think --docbuild should disappear and be replaced by direct call to python -m sage_docbuild (or possibly sage-python if it still makes sense). The current set up make things overly complex in src/sage/doc/Makefile and I am not sure putting things back into the main sage script makes it any better.
If we have any downstream using the command, I suggest we issue a deprecation message.
I'm a little concerned about things breaking if we just use python -m sage_docbuild, based on this snippet from sage-site:
if [ "$1" = "-docbuild" -o "$1" = "--docbuild" ]; then
# Redirect stdin from /dev/null. This helps with running TeX which
# tends to ask interactive questions if something goes wrong. These
# cause the build to hang. If stdin is /dev/null, TeX just aborts.
shift
# Trac #30002: ensure an English locale so that it is possible to
# scrape out warnings by pattern matching.
export LANG=C
export LANGUAGE=C
# See #30351: bugs in macOS implementations of openblas/libgopm can cause
# docbuild to hang if multiple OpenMP threads are allowed.
if [ `uname` = 'Darwin' ]; then
export OMP_NUM_THREADS=1
fi
# Trac #33650: Make sure that user configuration of Jupyter does not
# shadow our sagemath kernel when jupyter-sphinx is invoked
export JUPYTER_CONFIG_DIR=/doesnotexist
export JUPYTER_CONFIG_PATH=/doesnotexist
export JUPYTER_DATA_DIR=/doesnotexist
export JUPYTER_PATH=/doesnotexist
exec sage-python -m sage_docbuild "$@" </dev/null
fi
I'll admit that I don't have some of that baggage in sage-on-gentoo. If I was needing any of that stuff to build the doc, I would set it up before running the make invocation.
The LANG/LANGUAGE is something I expect from my environment for sanity (possibly a mistake :) ). The darwin thing could be handled if I go back to supporting gentoo-prefix on Mac. I build in a sandbox where user settings for jupyter will not affect me (gentoo-prefix may need checking for that scenario).
The /dev/null thing is probably something that need to be added to what I have done so far.
I am mostly seeing sage --docbuild as a relic from the past, but yes that cruft needs attention.
Replying to @kiwifb:
I am mostly seeing
sage --docbuildas a relic from the past
In #29941, I am making src/bin/sage part of a small basic distribution sagemath-environment, so that users can invoke, for example, sage --sh even when nothing else of Sage is installed. Options such as sage --docbuild, of course, will not work when nothing else is installed -- so the script could inform users what to install in this case.
Description changed:
---
+++
@@ -2,5 +2,5 @@
It was moved in #29111 to `build/bin/sage-site`, but it does have some (limited - #30475) functionality for users.
-**sage-docbuild** would be declared as an `extras-require` of **sagemath-standard**.
+**sage-docbuild** would be declared as an `extras-require` of **sagemath-standard**. #29941 also declares it as an `extras-require` of **sagemath-environment**.
Description changed:
---
+++
@@ -2,5 +2,5 @@
It was moved in #29111 to `build/bin/sage-site`, but it does have some (limited - #30475) functionality for users.
-**sage-docbuild** would be declared as an `extras-require` of **sagemath-standard**. #29941 also declares it as an `extras-require` of **sagemath-environment**.
+**sage-docbuild** would be declared as an `install-requires` of **sagemath-standard**. #29941 also declares it as an `extras-require` of **sagemath-environment**.
Branch: public/33795
Author: Kwankyu Lee
Branch pushed to git repo; I updated commit sha1. New commits:
e266569 | Move -docbuild from sage-site to sage |
Commit: e266569
Is this what to be done here?
LGTM, but this comment:
+ # Redirect stdin from /dev/null. This helps with running TeX which
+ # tends to ask interactive questions if something goes wrong. These
+ # cause the build to hang. If stdin is /dev/null, TeX just aborts.
is in a strange place (already in the original).
It would be better placed just before
+ exec sage-python -m sage_docbuild "$@" </dev/null
Branch pushed to git repo; I updated commit sha1. New commits:
fc9b96f | Move a comment to the right place |
Replying to @mkoeppe:
It would be better placed just before
+ exec sage-python -m sage_docbuild "$@" </dev/null
Right. Done.
Reviewer: Matthias Koeppe
Changed branch from public/33795 to fc9b96f