Hi,
I see that distutils2 promotes storing documentation in docs/ directory while Python sources use Doc/ I'd like to see this changed before distutils2 is released beta.
In my projects checkouts there are 80 project that use doc/ directories. Among these are: - subversion - hg - sphinx - trac - scons - twisted
docs/ directory is used by 61 project, the most famous are: - xalan - fop - moinmoin - cmd2 - googlecl
There are some arguments for 'doc/': 1. there is no plural for 'documentation' 2. bin/ is a common name for storing executables, although there is plural for 'binary' 3. we still use src/ instead of sources/
Any thoughts/objections? -- anatoly t.
I prefer docs. It seems more natural.
Michael
On 21 September 2010 11:35, anatoly techtonik techtonik@gmail.com wrote:
Hi,
I see that distutils2 promotes storing documentation in docs/ directory while Python sources use Doc/ I'd like to see this changed before distutils2 is released beta.
In my projects checkouts there are 80 project that use doc/ directories. Among these are:
- subversion
- hg
- sphinx
- trac
- scons
- twisted
docs/ directory is used by 61 project, the most famous are:
- xalan
- fop
- moinmoin
- cmd2
- googlecl
There are some arguments for 'doc/':
- there is no plural for 'documentation'
- bin/ is a common name for storing executables, although there is
plural for 'binary' 3. we still use src/ instead of sources/
Any thoughts/objections?
anatoly t. _______________________________________________ Distutils-SIG maillist - Distutils-SIG@python.org http://mail.python.org/mailman/listinfo/distutils-sig
On Tue, Sep 21, 2010 at 12:38, Michael Foord fuzzyman@voidspace.org.uk wrote:
I prefer docs. It seems more natural.
Me too. I think I got the habit of using "docs" instead of "doc" from some Zope guys.
http://www.google.com/search?q=site:svn.zope.org+inurl:doc ~600 results http://www.google.com/search?q=site:svn.zope.org+inurl:docs ~ 13000 results
Attila
Am 21.09.2010 12:35, schrieb anatoly techtonik:
Hi,
I see that distutils2 promotes storing documentation in docs/ directory while Python sources use Doc/ I'd like to see this changed before distutils2 is released beta.
In my projects checkouts there are 80 project that use doc/ directories. Among these are:
- subversion
- hg
- sphinx
- trac
- scons
- twisted
docs/ directory is used by 61 project, the most famous are:
- xalan
- fop
- moinmoin
- cmd2
- googlecl
There are some arguments for 'doc/':
- there is no plural for 'documentation'
FWIW, "docs" is probably short for "the documents".
That said, I have no preference and as long as a solution works with both doc/ and docs/ it's fine with me.
Georg
anatoly techtonik techtonik@gmail.com writes:
There are some arguments for 'doc/':
- there is no plural for 'documentation'
- bin/ is a common name for storing executables, although there is
plural for 'binary' 3. we still use src/ instead of sources/
* ‘doc/’ is consistent with the standardised directory name on many operating systems (those that inspired, or are based on, the FHS)
I don't think a vote is appropriate (I think the choice should be made on merit, not popularity), but if anyone's counting, I prefer ‘doc/’.
On Sep 21, 2010, at 01:35 PM, anatoly techtonik wrote:
I see that distutils2 promotes storing documentation in docs/ directory while Python sources use Doc/ I'd like to see this changed before distutils2 is released beta.
What does "promotes" mean? That only docs/ can be used?
In my projects checkouts there are 80 project that use doc/ directories. Among these are:
- subversion
- hg
- sphinx
- trac
- scons
- twisted
docs/ directory is used by 61 project, the most famous are:
- xalan
- fop
- moinmoin
- cmd2
- googlecl
So, almost evenly split. :)
I'm with Michael, I prefer docs/ and that's what I use for Mailman and all my libraries. It just *seems* righter. ;)
I still don't quite know in what way distutils2 promotes docs/ but I do think both choices need to be easily supported. Also for unittest2, since my docs/ directories just happen to also contain tests.
-Barry
On Tue, Sep 21, 2010 at 2:57 PM, Barry Warsaw barry@python.org wrote:
I see that distutils2 promotes storing documentation in docs/ directory while Python sources use Doc/ I'd like to see this changed before distutils2 is released beta.
What does "promotes" mean? That only docs/ can be used?
upload_docs command will extract documentation from 'docs/' by default. I wouldn't bring this question if it could also process 'doc/' in cases where 'docs/' are absent. You can specify upload directory explicitly, but sometimes you'd really like it to just work.
On Sep 21, 2010, at 05:20 PM, anatoly techtonik wrote:
On Tue, Sep 21, 2010 at 2:57 PM, Barry Warsaw barry@python.org wrote:
I see that distutils2 promotes storing documentation in docs/ directory while Python sources use Doc/ I'd like to see this changed before distutils2 is released beta.
What does "promotes" mean? That only docs/ can be used?
upload_docs command will extract documentation from 'docs/' by default. I wouldn't bring this question if it could also process 'doc/' in cases where 'docs/' are absent. You can specify upload directory explicitly, but sometimes you'd really like it to just work.
Gotcha, thanks.
Yes it should definitely use doc/ if docs/ is missing. 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. 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 ;).
-Barry
On Tue, Sep 21, 2010 at 5:34 PM, Barry Warsaw barry@python.org wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
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. 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 ;).
Well, I may think that I've fixed my problem, but until fix is integrated, I can't tell. -- anatoly t.
On Sat, Sep 25, 2010 at 8:41 PM, anatoly techtonik techtonik@gmail.com wrote:
On Tue, Sep 21, 2010 at 5:34 PM, Barry Warsaw barry@python.org wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
Thanks for the diff. Would you mind adding a tiny little test in test_upload_docs.test_default_uploaddir
I'll be happy to merge tour change then.
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.
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/
Regards Tarek
On Sep 27, 2010, at 09:55 AM, Tarek Ziadé wrote:
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.
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?
-Barry
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
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
On Mon, Sep 27, 2010 at 10:55 AM, Tarek Ziadé ziade.tarek@gmail.com wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
Thanks for the diff. Would you mind adding a tiny little test in test_upload_docs.test_default_uploaddir
I'll be happy to merge tour change then.
Added unittest, modified version is attached and is also updated on codereview.
On Wed, Sep 29, 2010 at 11:30 AM, anatoly techtonik techtonik@gmail.com wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
Thanks for the diff. Would you mind adding a tiny little test in test_upload_docs.test_default_uploaddir
I'll be happy to merge tour change then.
Added unittest, modified version is attached and is also updated on codereview.
The attached patch in this letter should be better suited for import.
Pushed at http://hg.python.org/distutils2/rev/37f948f6be6c
Thanks to all !
On Wed, Sep 29, 2010 at 10:40 AM, anatoly techtonik techtonik@gmail.com wrote:
On Wed, Sep 29, 2010 at 11:30 AM, anatoly techtonik techtonik@gmail.com wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
Thanks for the diff. Would you mind adding a tiny little test in test_upload_docs.test_default_uploaddir
I'll be happy to merge tour change then.
Added unittest, modified version is attached and is also updated on codereview.
The attached patch in this letter should be better suited for import.
-- anatoly t.
On Sep 25, 2010, at 09:41 PM, anatoly techtonik wrote:
On Tue, Sep 21, 2010 at 5:34 PM, Barry Warsaw barry@python.org wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
I commented.
-Barry
On Tue, Sep 28, 2010 at 3:36 PM, Barry Warsaw barry@python.org wrote:
Yes it should definitely use doc/ if docs/ is missing.
Attached patch. Review in context at http://codereview.appspot.com/2269042
I commented.
Thanks. Updated. =) -- anatoly t.
On Tue, Sep 21, 2010 at 10:20 AM, anatoly techtonik techtonik@gmail.com wrote:
upload_docs command will extract documentation from 'docs/' by default. I wouldn't bring this question if it could also process 'doc/' in cases where 'docs/' are absent. You can specify upload directory explicitly, but sometimes you'd really like it to just work.
Of course, we'd have to define what "just work" means here. I'd be fine having to always tell upload_docs where to look, provided I can do that in the setup.cfg d2 uses.
That said, I don't *mind* if it looks for both docs/ and doc/, or even care which it looks for first.
-Fred
-- Fred L. Drake, Jr. <fdrake at acm.org> "A storm broke loose in my mind." --Albert Einstein
On Tue, Sep 21, 2010 at 4:38 PM, Fred Drake fdrake@acm.org wrote:
On Tue, Sep 21, 2010 at 10:20 AM, anatoly techtonik techtonik@gmail.com wrote:
upload_docs command will extract documentation from 'docs/' by default. I wouldn't bring this question if it could also process 'doc/' in cases where 'docs/' are absent. You can specify upload directory explicitly, but sometimes you'd really like it to just work.
Of course, we'd have to define what "just work" means here. I'd be fine having to always tell upload_docs where to look, provided I can do that in the setup.cfg d2 uses.
That said, I don't *mind* if it looks for both docs/ and doc/, or even care which it looks for first.
+1 -- trying both seems fine as I don't think we want to push hard on any convention here.
Tarek
participants (9)
-
anatoly techtonik -
Attila Oláh -
Barry Warsaw -
Ben Finney -
Fred Drake -
Georg Brandl -
Michael Foord -
Tarek Ziadé -
Éric Araujo