[Distutils] docs/ vs doc/

[Éric Araujo]

Hi,

Old thread revival!  I was going through my archive and noticed this
unanswered message from late September which prompted me to do a bit of
research.

>>>> However, upload_docs
>>>> never quite works out of the box for me anyway.  First, it insists
>>>> on an index.html file, which my Sphinx builds never seem to write,
>>>> so I always have to add a symlink.
>> Barry, do you mean that you have all files generated by Sphinx but not
>> index.html ? That's weird, Sphinx should generate it like the others.
> Except that I don't have an index.txt file.  It kind of doesn't make sense.  I
> use buildout and have this in my buildout.cfg:
> 
> [docs]
> recipe = z3c.recipe.sphinxdoc
> eggs = mailman [docs]
> index-doc = docs/README
> default.css =
> layout.html =
> extensions = sphinxconf
> 
> So what I end up doing is symlinking index.html to README.html before I
> upload.

I don’t know the recipe, but the “index-doc” settings clearly looks like
something that controls what the master page is called.  I guess it’s
because you want your README file to serve double duty as Sphinx front
page.  Now for the good news: I found you a way to make Sphinx use that
file as index.html:
http://osdir.com/ml/sphinx-dev/2010-10/msg00082.html

One may argue that upload_docs should just bundle *.html files, without
imposing the existence of index.html; I think the check is useful.

>>>  Second, it doesn't seem to play nicely with the location
>>>> that my buildout-based builds puts the docs, so I always also have
>>>> to use --upload-dir.  Yes, it would be nice if both of these
>>>> problems were fixed too. Yes, I should report them as bugs (or just
>>>> fix 'em ;).
>> How would you fix the second issue ? e.g. if the docs is not in docs/
>> or doc/
> That's a good question!  Maybe it's a buildout or recipe issue?

You can make the upload-dir setting persistent by putting it in your
setup.cfg.  Or if the recipe is used by a large part of the community,
open a feature request to have this directory automatically found if
neither docs nor doc exist.  What is the directory path, btw?

Regards