Opened 9 years ago

Last modified 5 years ago

#10831 needs_work enhancement

Make python support SAGE_SPKG_INSTALL_DOCS

Reported by: jason Owned by: tbd
Priority: major Milestone: sage-6.4
Component: packages: standard Keywords:
Cc: Merged in:
Authors: Jason Grout Reviewers:
Report Upstream: N/A Work issues:
Branch: Commit:
Dependencies: Stopgaps:

Description (last modified by jason)

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

Attachments (2)

10831-deps.patch (1015 bytes) - added by jason 9 years ago.
Apply to deps (probably needs to be redone after #9433)
10831-install.patch (247 bytes) - added by jason 9 years ago.
apply to the spkg/install file

Download all attachments as: .zip

Change History (17)

comment:1 Changed 9 years ago by jason

  • Description modified (diff)
  • Status changed from new to needs_review

comment:2 Changed 9 years ago by drkirkby

  • Status changed from needs_review to needs_info

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

comment:3 Changed 9 years ago by drkirkby

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

comment:4 follow-up: Changed 9 years ago by jason

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.

comment:5 in reply to: ↑ 4 ; follow-up: Changed 9 years ago by drkirkby

Replying to jason:

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

comment:6 Changed 9 years ago by jason

  • Status changed from needs_info to needs_work

comment:7 in reply to: ↑ 5 Changed 9 years ago by jason

Replying to drkirkby:

Replying to jason:

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.

comment:8 Changed 9 years ago by jason

(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

comment:9 Changed 9 years ago by jason

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?

Changed 9 years ago by jason

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

Changed 9 years ago by jason

apply to the spkg/install file

comment:10 Changed 9 years ago by jason

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?

comment:11 Changed 8 years ago by jason

See #11197 for building docs after Sage is built.

comment:12 Changed 6 years ago by jdemeyer

  • Milestone changed from sage-5.11 to sage-5.12

comment:13 Changed 6 years ago by vbraun_spam

  • Milestone changed from sage-6.1 to sage-6.2

comment:14 Changed 5 years ago by vbraun_spam

  • Milestone changed from sage-6.2 to sage-6.3

comment:15 Changed 5 years ago by vbraun_spam

  • Milestone changed from sage-6.3 to sage-6.4
Note: See TracTickets for help on using tickets.