homepage

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

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.

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.

Tim,
Post up a patch of what you have up to now and I will look at it today.

Patch against sphinx r59269. Split on "/" and local os.sep. Causes
problems with sphinx-web under native Win32.

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.

Really great that you're doing this! Many thanks!
(Yes, I must admit that I was sloppy there...)

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.

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.

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>

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

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

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!