Fix the way sage/misc/sagedoc.py reads doc/common/builder.py

[jdemeyer]

The following code from sage/misc/sagedoc.py is horrible:

        # check if any documentation is missing.  first read the start
        # of SAGE_ROOT/devel/sage/doc/common/builder.py to find list
        # of languages, documents, and documents to omit
        doc_path = os.path.join(ROOT, 'devel', 'sage', 'doc')
        builder = open(os.path.join(doc_path, 'common', 'builder.py'))
        s = builder.read()[:1000]
        builder.close()
        # list of languages
        lang = []
        idx = s.find("LANGUAGES")
        if idx != -1:
            start = s[idx:].find('[')
            end =  s[idx:].find(']')
            if start != -1 and end != -1:
                lang = s[idx+start+1:idx+end].translate(None, "'\" ").split(",")
        # documents in SAGE_ROOT/devel/sage/doc/LANG/ to omit
        omit = []
        idx = s.find("OMIT")
        if idx != -1:
            start = s[idx:].find('[')
            end =  s[idx:].find(']')
            if start != -1 and end != -1:
                omit = s[idx+start+1:idx+end].translate(None, "'\" ").split(",")

Component: documentation

Author: Jeroen Demeyer

Reviewer: Mike Hansen, Volker Braun

Merged: sage-4.6.2.alpha4

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

[mwhansen]

Reviewer: Mike Hansen

[mwhansen]

comment:2

The method of saving the old path in this patch doesn't work since oldpath = sys.path has them both "pointing" to the same object. Then, when you change sys.path, you also change oldpath. You could change it to something like oldpath = sys.path[:]

[jdemeyer]

comment:3

Replying to @mwhansen:

The method of saving the old path in this patch doesn't work since oldpath = sys.path has them both "pointing" to the same object. Then, when you change sys.path, you also change oldpath. You could change it to something like oldpath = sys.path[:]

Thanks! I've solved the problem with

sys.path = oldpath + [os.path.join(ROOT, 'devel', 'sage', 'doc', 'common')]

[nexttime]

comment:4

I wonder if the docbuilder "options" should go into a separate file, such that we don't (have to) import the whole builder.py.

[jdemeyer]

comment:5

Replying to @nexttime:

I wonder if the docbuilder "options" should go into a separate file, such that we don't (have to) import the whole builder.py.

That's a possibility, but I think the current approach works fine (and builder.py is not such a big file).

[nexttime]

comment:6

Replying to @jdemeyer:

Replying to @nexttime:

I wonder if the docbuilder "options" should go into a separate file, such that we don't (have to) import the whole builder.py.

That's a possibility, but I think the current approach works fine (and builder.py is not such a big file).

Well, importing the whole file could have very strange side-effects, at least in the future.

Another reason is users are likely to edit (just) these options. (Which however is sub-optimal by itself...)

[jdemeyer]

comment:7

I can see your point, maybe it would not be a bad idea to split the configuration from the code...

[jdemeyer]

Attachment: 10351_sagedoc.patch.gz

SAGELIB patch

[vbraun]

Changed reviewer from Mike Hansen to Mike Hansen, Volker Braun

[vbraun]

comment:10

Definite improvement ;-)

[jdemeyer]

Merged: sage-4.6.2.alpha4