sphinx-build

[Jean]

There may be a way around the sphinx-build.py issue. Here are the
details for MacOS X and I need you the check your specific
configuration(s).

It turns out Sphinx, rather easy_install *does* install the sphinx-
build and sphinx-quickstart scripts in the .../bin directory of the
Python release. In that .../bin directory are also links to or copies
of the Python binaries.

But there is no link for sphinx-build script in /usr/local/bin where
links to Python scripts or binaries are typically installed by pre-
built Python distributions for MacOS X. That makes sense, I guess.

In addition, on MacOS X, sys.executable does *not* end in the .../bin
or /usr/local/bin directory but somewhere inside a MacOS X specific
Resource/Package/Content file.

Therefore, we can not use sys.executable to locate sphinx-build.
But the location of the sphinx-build script is the .../bin directory
inside the sys.prefix or sys.exec_prefix.

Therefore, to run a Python-version-specific sphinx-build, we should
prepend the path of the bin directories in sys.prefix and
sys.exec_prefix to the PATH environment variable before invoking
'sphinx-build'. Or we could use a fully qualified path for sphinx-
build.

I will try this next. In the mean time, could you check your Python
and Sphinx installations and see if there is a file sphinx-build in
the bin directory under sys.prefix and/or sys.exec_prefix. If so,
we are OK.

/Jean

[Jean]

I just committed r133 of run.py and it tries to find the sphinx-build
script installed in the running Python build. That seems to work fine
now, at least for MacOS X.

But, I still have not worked out the case when there is no Sphinx
installed in the current Python build. Perhaps, if the script-build
can not be found, run.py should fall back to using ./doc/sphinx-build
[.py]. But that script may not be a Python script, it could be
anything.

/Jean

[Jean]

One more thought on the sphinx-build fall back script. If no sphinx-
build can be found in the currently running Python, run.py could just
try to invoke sphinx-build as a default.

Inside the default sphinx-build script, any Python version could be
used to actually run Sphinx. That would allow run.py to be used with
different Python releases with or without Sphinx installed.

As long as the default sphinx-build script can be found by the _spawn
function in run.py. It should be since both subprocess.call and
os.spawnlp look for sphinx-build on the current PATH environment
variable.

/Jean

[Jean Brouwers]

I modified run.py to try what I suggested earlier and it works as expected.

My Python 2.3 does not have Sphinx installed and running

python2.3 run.py --html

invokes the sphinx-build script in ./doc. That script was modified
in the first line to use Python 2.6: #!/usr/bin/env python2.6 .

/Jean

[Jean Brouwers]

The latest run.py committed as r134 uses the installed sphinx-build
if present, otherwise ./doc/sphinx-build if that one exists and
otherwise sphinx-build as-is. If the command fails, a message will
be printed (same for other run.py commands)

Other changes are the --upload option (not yet activated and tested)
for distributions and a few minor, mostly cometic things.

/Jean

PS) Also, I tried creating the LaTex docs but Sphinx 0.5 chokes and
runs into an error (for all Sphinx 0.5 releases installed in Python
2.4, 2.5 and 2.6 on MacOS X). It is very difficult to determine what
is causing the problem and it would certainly be nice if Sphinx had an
option to show more of the context of an error. After changing
several doc/source files, it seems there might be too many header
nesting or indentation levels (although that is not an issue for HTML,
appearently). The error message is very cryptic and just prints the
name of one of the (sub)titles in the muppy/tutorial.rst file. But if
the offending header or title is changed, the problem moves.

[Jean Brouwers]

Forgot to mention, we can remove the doc/sphinx-build.py file from
the trunk. No longer needed.

/Jean

[Jean Brouwers]

Here is the error from Sphinx LaTex. This is the very latest update
of the doc files.

% run.py -L

Creating LaTex (PDF) documention (32-bit Python 2.6)
====================================================
Sphinx error:
too many nesting section levels for LaTeX, at heading: Preparations
Running '/Library/Frameworks/Python.framework/Versions/2.6/bin/sphinx-build
-b ...' failed with exit status 1

The last line is reported by run.py.

/Jean

[Robert Schuppenies]

Hi Jean.

Thanks for the good work, now it works. I have made two minor
adjustments. First, I changed the order in which sphinx-build
scripts are picked to look into .doc/ first. I think usually
developers won't have this script, but if they do, it should be
used. Do you agree?

Second of all, I would like to run sphinx in quiet mode only if
run.py runs in verbosity 0. The reason is that sphinx does not show
doctest or linkcheck errors otherwise. This would let us miss
failures in the expected behavior. Is this okay for you guys?

cheers,
robert

btw, I have removed the doc/sphinx-build file from the repository.

[Robert Schuppenies]

Jean Brouwers wrote:
> Here is the error from Sphinx LaTex. This is the very latest update
> of the doc files.
>
> % run.py -L
>
> Creating LaTex (PDF) documention (32-bit Python 2.6)
> ====================================================
> Sphinx error:
> too many nesting section levels for LaTeX, at heading: Preparations
> Running '/Library/Frameworks/Python.framework/Versions/2.6/bin/sphinx-build
> -b ...' failed with exit status 1
>
> The last line is reported by run.py.

This is a latex/sphinx issue and your guess that it has to do with
the level of sections is correct. Latex per default has only seven
levels, and we have more than that. sphinx isn't expecting this,
which then leads to a crash. More levels are possible for latex, but
not for sphinx currently. I filed a bug report at
http://bugs.python.org/issue4436

If it bugs you right now, we can think about restructuring the docs,
but this would be a bit of work.

cheers,
robert

[Ludwig Hähne]

Robert Schuppenies wrote on 26.11.2008 09:30:
> Second of all, I would like to run sphinx in quiet mode only if
> run.py runs in verbosity 0. The reason is that sphinx does not show
> doctest or linkcheck errors otherwise. This would let us miss
> failures in the expected behavior. Is this okay for you guys?

Yes.

Speaking about verbosity: I've removed the error message in setup.py,
because passing '-verbose 3' to setup.py does not have the desired
effect (was not passed to test/runtest.py). '-verbose 3' is now the
default when runtest is invoked by setup.py. This way, the error
messages might actually reveal what the problem is (if there's a problem).

Ludwig

[Jean Brouwers]

After all this, it might even be better to simplify the whole thing
and handle Sphinx like PyChecker: run ./tools/sphinx.py or
./tools/sphinx-build.py. If Sphinx is not installed in the current
Python, that script can handle that if needed.

No problem with changing the quiet mode.

Another things is debugging the docs, e.g. the error Sphinx for the
LaTeX build. I have not found anything yet on that.

/Jean

[Jean Brouwers]

Good! My only purpose was (1) to check that run.py -L works and (2)
get some experience with Sphinx.

/Jean

[Jean Brouwers]

Let me know before I proceed with checking in yet another run.py and a
new ./tools/sphinx.py. The former invokes the latter and the latter
tries to import Sphinx and if that fails, exec's 'shpinx-build'.

That is a far cleaner, simpler solution than the lookup magic in the
current run.py and provides the same benefits: if Sphinx is installed
in the current Python, it will be used. If not 'sphinx-build'.is
invoked.

/Jean

[Robert Schuppenies]

Please go ahead :)

[Jean Brouwers]

Committed. If all is well, remove ./doc/sphinx-build.

/Jean