[Distutils] docs/ vs doc/

[Barry Warsaw]

On Feb 19, 2011, at 12:57 AM, Éric Araujo wrote:

>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.

\o/

>>>>> 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

Thanks, but I tried this and couldn't get it working.  Actually, from Georg's
response, it sounds like html_index isn't even supported any more.

My own crappy workaround is this bit of ugliness in my conf.py file:

def index_html():
    cwd = os.getcwd()
    try:
        os.chdir('build/sphinx/html')
        os.symlink('README.html', 'index.html')
        print 'index.html -> README.html'
    finally:
        os.chdir(cwd)

import atexit
atexit.register(index_html)

The interesting thing is that this works with 'python setup.py build_sphinx'
but not with 'make html' (using Sphinx's generated Makefile) because of the
different build path defaults.  OTOH, the Makefile does have this nice target:

pypi: html
	(cd _build/html; \
	 rm -f index.html; \
	 ln -s README.html index.html; \
	 zip -r ../pypi .)

So 'make html && make pypi' leaves you with _build/pypi.zip that should be
directly uploadable.

>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?

Yep, I found the upload-dir setting for setup.cfg.  So after 'make pypi' a
'python setup.py upload_docs' DTRT.

Cheers,
-Barry
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 836 bytes
Desc: not available
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20110223/ffb4ceae/attachment-0001.pgp>