Make python support SAGE_SPKG_INSTALL_DOCS

[jasongrout]

This is a bit tricky since we need sphinx and other things installed before we can build the docs, but sphinx and the other things depend on python. To resolve this circular dependency, we try to import sphinx. If we can't import sphinx, then we exit without error with a message that you should install sphinx and related tools first and then try building the docs again. This means that in order to use the environment variable, you have to install the python spkg twice, since we don't have an option to just build docs without building python. But maybe that's worth it for someone that just wants the python docs.

The new spkg is here: http://sage.math.washington.edu/home/jason/python-2.6.4.p10.spkg

Component: packages: standard

Reviewer: Dima Pasechnik

Issue created by migration from https://trac.sagemath.org/ticket/10831

[sagetrac-drkirkby]

comment:2

See comments on #10828

I wonder if it might be sensible to create a new package called - python-documentation-1.0.spkg in order to resolve this circular dependency problem.

That new python-documentation-1.0.spkg gets built after both python and sphinx are built. This package then copies the contents of the python package from the python.spkg, extracts it, then builds only the documentation - not all of Python if at all possible.

Otherwise, the build will fail for sure for everyone, which is off-putting to newcomers, even if old hands know how to get around the problem. The ability to type 'make' then go away and leave it will be lost if the build fails on this each time.

dave

[sagetrac-drkirkby]

comment:3

I see your note that's its impossible to build just the docs for Python.

Another option, which would be quicker is to

• If SAGE_SPKG_INSTALL_DOCS=yes, build and install Python, but tar up the build and stick that in a temporary directory somewhere.
• After sphinx and whatever else are built, extract that tar file, and just build the documentation.

Somehow I think we should automate this, so Python's documentation gets built without manual intervention. It can't be rocket science to do this. If the worst comes to the worst, just build Python twice if SAGE_SPKG_INSTALL_DOCS=yes

Dave

[jasongrout]

comment:4

Yes, I suppose worst-case is just adding a python-docs target to the deps file that builds python again after sphinx is installed. A slightly better case is adding a python-docs target that defines an environment variable SAGE_PYTHON_BUILD=no or something and then re-installs the python spkg. Then modify the python spkg to check for that variable and not actually build python if that variable is no.

[sagetrac-drkirkby]

comment:5

Replying to @jasongrout:

Yes, I suppose worst-case is just adding a python-docs target to the deps file that builds python again after sphinx is installed.

That's quite easy to do.

A slightly better case is adding a python-docs target that defines an environment variable SAGE_PYTHON_BUILD=no or something and then re-installs the python spkg. Then modify the python spkg to check for that variable and not actually build python if that variable is no.

Ideally though we don't want the user to have to mess with that environment variable. I think this can be automated.

As long as there's not an issue with hard-coded paths (which may make the documentation useless if Sage is moved), then I think a temporary tar file is the best solution, as it will save a lot of time. Python is a big package to build twice if it is unnecessary.

This needs a bit of thought, and its late here, so I'm going to bed.

Dave

[jasongrout]

comment:7

Replying to @sagetrac-drkirkby:

Replying to @jasongrout:

Yes, I suppose worst-case is just adding a python-docs target to the deps file that builds python again after sphinx is installed.

That's quite easy to do.

A slightly better case is adding a python-docs target that defines an environment variable SAGE_PYTHON_BUILD=no or something and then re-installs the python spkg. Then modify the python spkg to check for that variable and not actually build python if that variable is no.

Ideally though we don't want the user to have to mess with that environment variable. I think this can be automated.

Yep. I'm thinking that the python-docs target will

• Check to see if SAGE_SPKG_INSTALL_DOCS=yes, and if so:
• set the SAGE_SPKG_PYTHON_BUILD=no variable and then reinstall the python spkg (which will then just build the docs, but not python).

The user won't ever have to deal with that environment variable---it's all behind the scenes.

[jasongrout]

comment:8

(note that the makefile wouldn't export SAGE_SPKG_PYTHON_BUILD, but would do the equivalent of SAGE_SPKG_PYTHON_BUILD=no sage -i python

[jasongrout]

comment:9

I'm a little lost in the deps file. I've attached a patch which I think does what we want (add a new target that reinstalls the python spkg, but with a local variable set so that python isn't actually rebuilt). Comments, David?

[jasongrout]

Attachment: 10831-deps.patch.gz

Apply to deps (probably needs to be redone after #9433)

[jasongrout]

apply to the spkg/install file

[jasongrout]

comment:10

Attachment: 10831-install.patch.gz

Okay, I think I made the necessary changes to the deps and install file. The assumption is that the file docs_python....spkg is a symbolic link to the python spkg. Is this solution a good way to do things?

[jasongrout]

comment:11

See #11197 for building docs after Sage is built.

[mkoeppe]

Changed author from Jason Grout to none

[mkoeppe]

comment:16

outdated, should close

[dimpase]

Reviewer: Dima Pasechnik