classification
Title: 'without make' documentation build anomaly
Type: behavior Stage:
Components: Documentation, Documentation tools (Sphinx) Versions: Python 3.0
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: georg.brandl Nosy List: JosephArmbruster, georg.brandl, tim.golden
Priority: low Keywords:

Created on 2007-11-29 15:15 by JosephArmbruster, last changed 2007-12-03 22:42 by georg.brandl. This issue is now closed.

Files
File name Uploaded Description Edit
sphinx-r59269.patch tim.golden, 2007-12-02 17:24
sphinx-r59286.patch tim.golden, 2007-12-03 11:43
Messages (13)
msg57931 - (view) Author: Joseph Armbruster (JosephArmbruster) Date: 2007-11-29 15:15
When I run the following from a windows command line, the resulting html
can not be browsed stand-alone:

python tools/sphinx-build.py -bhtml . build/htmlwin

It looks like the paths are getting hosed up; for example:

htmlcygwin/c-api/index.html contains:
<link rel="stylesheet" href="../style/default.css" type="text/css">
<link rel="stylesheet" href="../style/pygments.css" type="text/css">

htmlcmd/c-api/index.html contains:
<link rel="stylesheet" href="style/default.css" type="text/css">
<link rel="stylesheet" href="style/pygments.css" type="text/css">

Notes:

These seemed to work fine:

- building target html it in cygwin using make
- building target html in cygwin without make
- building target htmlhelp in cmd without make then generating chm
msg58084 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2007-12-02 12:49
Looks like it's the backslash as Windows path separator confusing the
sphinx.util.relative_uri function. I'll try to put a patch together,
although I'm not sure if relative_uri should use os.sep or whether the
paths should be canonicalised before getting there. I'll try with os.sep
to start with.
msg58090 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2007-12-02 17:14
I'm a little flummoxed. Patching relative_uri in the
sphinx/util/__init__.py to re.split on ("/" + os.sep) sorts out the
static generation. But it seems to introduce a couple of problems with
the web-server version of the docs. One is that links end up without a
category: http://localhost:3000/windows/ instead of
http://localhost:3000/using/windows/. The other is that, even if you put
the URLs in by hand, they don't work whereas /using%5cwindows *does*
work. Which suggests that the windows-y path is being stored somewhere
in the pickle files.

So now we're stretched two ways: the HTML needs /-delimited names to
work; the pickled files need \-delimited. I'm still looking at it, but
if anyone has more knowledge that I have (couldn't exactly have less)
then please feel free to chip in.
msg58091 - (view) Author: Joseph Armbruster (JosephArmbruster) Date: 2007-12-02 17:18
Tim,

Post up a patch of what you have up to now and I will look at it today.
msg58092 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2007-12-02 17:24
Patch against sphinx r59269. Split on "/" and local os.sep. Causes
problems with sphinx-web under native Win32.
msg58101 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2007-12-02 21:15
OK, hacking away a bit further, I think I've found a solution, but I'll
need to tidy it up a bit. In essence, the problem is that the "filename"
is trying to be two things: the pointer for the local filesystem, and
the uri for the web server. On *nix, this will pretty much work. On
Windows -- and elsewhere, it won't.

My approach is to treat the filename a little like unicode: decode to
"web-format" on the way in; encode to "local-format" on the way out. In
practice, this resolves to a bunch of .replace(path.sep, "/") calls in
one place and .replace("/", path.sep) in the comparatively rare cases we
actually need to read the local filesystem.

I realise that, on Windows, I could get a bit hacky and just assume that
"/" will work throughout. But that obviously fails now for things like
VMS and in the future for the hypothetical filesystem which uses "." as
its separator etc.

I'm still working it through. The web and html versions are certainly
working but I need to check out htmlhelp which has its own special needs.
msg58102 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2007-12-02 21:40
Really great that you're doing this! Many thanks!

(Yes, I must admit that I was sloppy there...)
msg58105 - (view) Author: Joseph Armbruster (JosephArmbruster) Date: 2007-12-02 22:47
Tim,

Appears you are on your way to a fix.  If you need it tested on an
alternate windows machine, post up and i'll run through it.
msg58115 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2007-12-03 11:43
The attached patch against r59286 tries to tease apart the uses of
filename by adding "webify_filepath" and "unwebify_filepath" functions
to sphinx.utils which are then used throughout the app to convert from
filesystem-separated to web-separated paths and back. A WEB_SEP constant
has been defined principally to make its purpose clear in case a
constant "/" was thought to have been a hangover from the code's *nix
origins.

The result has been tested by building manually, ie by invoking python
tools\sphinx-build.py with appropriate params under Win32 native only.
The html, web and htmlhelp versions all style up and function correctly.
It would obviously benefit from testing under Cygwin and *nix. I'm
particularly keen to see it it works on a filesystem which doesn't allow
"/" as a separator.
msg58130 - (view) Author: Joseph Armbruster (JosephArmbruster) Date: 2007-12-03 16:31
The good news:

At a glance, the following look good:
- building target html in cmd
- building target htmlhelp then generating chm
- building target html in cygwin
- building target htmlhelp then generating chm

The bad news [should a different bug be created for this?]

See cmdline.rst:
.. cmdoption:: -c <command>
.. cmdoption:: -m <module-name>
.. describe:: <script>

Looks like genindex.html is being generated with some iffy markup:
<dt>-c <command></dt>
msg58132 - (view) Author: Joseph Armbruster (JosephArmbruster) Date: 2007-12-03 16:36
Typo in my last comment:
- building target html in cmd
- building target htmlhelp then generating chm
- building target html in cygwin
- building target htmlhelp in cygwin then generating chm
msg58133 - (view) Author: Tim Golden (tim.golden) * (Python committer) Date: 2007-12-03 16:41
Joseph Armbruster wrote:
> The bad news [should a different bug be created for this?]
> 
> See cmdline.rst:
> .. cmdoption:: -c <command>
> .. cmdoption:: -m <module-name>
> .. describe:: <script>
> 
> Looks like genindex.html is being generated with some iffy markup:
> <dt>-c <command></dt>

I'm not sure which way round you're say this. On my system,
the markup is:

<dl class="cmdoption">
<dt id="cmdoption-c">
<tt class="descname">-c</tt><tt class="descclassname"> 
&lt;command&gt;</tt><a class="headerlink" href="#cmdoption-c" 
title="Permalink to this definition">ΒΆ</a></dt>
<dd><p>Execute ...</p></dd>
</dl>

Is this right? Or wrong? It doesn't look disastrous to me.
In either case, I doubt it's related to the path issues we've
been addressing in this Issue. Probably best to raise a new
Issue if you think there's a problem.

TJG
msg58163 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2007-12-03 22:38
I fixed the markup problem now, it was a missing escape filter in the
template. Well spotted!

I also applied the patch in r59309, so this should be fixed now. Many
thanks!
History
Date User Action Args
2007-12-03 22:42:33georg.brandlsetstatus: open -> closed
resolution: fixed
2007-12-03 22:38:44georg.brandlsetmessages: + msg58163
2007-12-03 16:41:06tim.goldensetmessages: + msg58133
2007-12-03 16:36:29JosephArmbrustersetmessages: + msg58132
2007-12-03 16:31:36JosephArmbrustersetmessages: + msg58130
2007-12-03 11:43:40tim.goldensetfiles: + sphinx-r59286.patch
messages: + msg58115
2007-12-02 22:47:39JosephArmbrustersetmessages: + msg58105
2007-12-02 21:40:23georg.brandlsetmessages: + msg58102
2007-12-02 21:15:05tim.goldensetmessages: + msg58101
2007-12-02 17:24:25tim.goldensetfiles: + sphinx-r59269.patch
messages: + msg58092
2007-12-02 17:18:57JosephArmbrustersetmessages: + msg58091
2007-12-02 17:14:59tim.goldensetmessages: + msg58090
2007-12-02 12:49:14tim.goldensetnosy: + tim.golden
messages: + msg58084
2007-11-30 19:20:26gvanrossumsetpriority: low
assignee: georg.brandl
nosy: + georg.brandl
2007-11-29 15:15:31JosephArmbrustercreate