Docbuilder changes sagetex.rst

[jdemeyer]

Install sage-5.8.beta2 and build the documentation. Now

$ touch devel/sage/doc/en/reference/misc/sagetex.rst
$ make doc

and you will see the following change appear:

doc/en/reference/misc/sagetex.rst

@@ -1 @@
-Installing and using SageTeX
-============================
+.. nodoctest
 
-SageTeX is a system for embedding computations and plots from Sage into
-LaTeX documents. It is included by default with Sage, so if you have
-installed Sage, you already have SageTeX. However, to get it to work,
-you need to make TeX aware of SageTeX. Instructions for that are in the
-"Make SageTeX known to TeX" section of the `Sage installation guide
-<http://sagemath.org/doc/installation/index.html>`_ (`this link
-<../../installation/index.html>`_ should take you to a local copy of the
-installation guide).
+.. _sagetex:
+
+MISSING TITLE
+=============
+
+.. This file has been autogenerated.
+
+
+.. automodule:: sagetex
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+

If this an autogenerated file, it should not be tracked by Mercurial. And why did all content get removed?

Making the file sagetex.rst unwritable shows where the file is written:

Traceback (most recent call last):
  File "/Users/buildbot/sage-5.8.beta2/devel/sage/doc/common/builder.py", line 45, in build_ref_doc
    getattr(ReferenceSubBuilder(doc, lang), format)(*args, **kwds)
  File "/Users/buildbot/sage-5.8.beta2/devel/sage/doc/common/builder.py", line 662, in _wrapper
    self.write_auto_rest_file(module_name.replace(os.path.sep, '.'))
  File "/Users/buildbot/sage-5.8.beta2/devel/sage/doc/common/builder.py", line 924, in write_auto_rest_file
    outfile = open(filename, 'w')
IOError: [Errno 13] Permission denied: '/Users/buildbot/sage-5.8.beta2/devel/sage/doc/en/reference/misc/sagetex.rst'

[jhpalmieri]

I think I may have seen something like this a long time ago, in the early stages of testing #6495, but then I thought it had to do with maybe not deleting the old doc output or something like that. Was this a build from scratch or an upgrade?

I think that the only OS X 10.6 system that I have access to is bsd.math.washington.edu, and I can't reproduce this there, at least after building the docs a few times with a freshly built Sage 5.8.beta2.

[jdemeyer]

Replying to jhpalmieri:

Was this a build from scratch or an upgrade?

I don't remember, it was on a buildbot machine (bsd.math), but I guess it was a build from scratch. On bsd.math look for /Users/buildbot/sage-5.8.beta2-14199.tar.bz2 which is a build with this problem.

[jhpalmieri]

Okay, I think I've figured it out: the problem is that "sagetex.rst" starts with "sage". See the attached patch.

[jdemeyer]

Maybe you should document better what's the purpose of the condition

if name.startswith('sage' + os.sep):

[jhpalmieri]

I added a comment to try to address your suggestion.