Re: [Python-Dev] Sphinx version for Python 2.x docs
Am 17.01.2012 19:02, schrieb Sandro Tosi: >> I should have given more info, as I wanted the opposite result :) >> file.next should not link to the next function but to the file.next >> method. Because Sphinx does not differentiate between >> meth/func/class/mod roles, :meth:`next` is not resolved to the nearest >> next method as one could expect but to the next function, so we have to >> use :meth:`~SomeClass.next` or :meth:`.next` (local ref markup) to get >> our links to methods. > > I tried :meth:`.next` but got a lots of : > > /home/morph/cpython/py27/Doc/library/stdtypes.rst:2372: WARNING: more > than one target found for cross-reference u'next': iterator.next, > multifile.MultiFile.next, csv.csvreader.next, dbhash.dbhash.next, > mailbox.oldmailbox.next, ttk.Treeview.next, nntplib.NNTP.next, > file.next, bsddb.bsddbobject.next, tarfile.TarFile.next, > generator.next > > so I ended up with :meth:`next` but it was still wrong. I've committed > 51e11b4937b7 which uses :meth:`~file.next` instead, and it works. No need to try, just read the docs :) `next` looks in the current (class, then module) namespaces. `.next` looks everywhere, so the match must be unique. So for something as common as "next", an explicit `file.next` is required. Georg ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
On Mon, Jan 16, 2012 at 16:42, Éric Araujo wrote: > Hi, > > Le 14/01/2012 15:31, Sandro Tosi a écrit : >> >> On Sat, Jan 14, 2012 at 04:24, Éric Araujo wrote: Doc/glossary.rst:520: WARNING: unknown keyword: nonlocal >>> >>> That’s a mistake I did in cefe4f38fa0e. This sentence should be removed. >> >> Do you mean revert this whole hunk: >> [...] >> >> or just "The :keyword:`nonlocal` allows writing to outer scopes."? > > > My proposal was to remove just that one last sentence, but the only > other change in the diff hunk is the addition of “by default”, which is > connected to the existence of nonlocal. Both changes, i.e. the whole > hunk, should be reverted (I think I’ll have time to do that today). I've reverted it with ef1612a6a4f7 Doc/library/stdtypes.rst:2372: WARNING: more than one target found for cross-reference u'next': >>> >>> Need to use :meth:`.next` to let Sphinx find the right target (more info >>> on request :) >> >> it seems what it needed to was :meth:`next` (without the dot). The >> current page links all 'next' in file.next() to functions.html#next, >> and using :meth:`next` does that. > > > I should have given more info, as I wanted the opposite result :) > file.next should not link to the next function but to the file.next > method. Because Sphinx does not differentiate between > meth/func/class/mod roles, :meth:`next` is not resolved to the nearest > next method as one could expect but to the next function, so we have to > use :meth:`~SomeClass.next` or :meth:`.next` (local ref markup) to get > our links to methods. I tried :meth:`.next` but got a lots of : /home/morph/cpython/py27/Doc/library/stdtypes.rst:2372: WARNING: more than one target found for cross-reference u'next': iterator.next, multifile.MultiFile.next, csv.csvreader.next, dbhash.dbhash.next, mailbox.oldmailbox.next, ttk.Treeview.next, nntplib.NNTP.next, file.next, bsddb.bsddbobject.next, tarfile.TarFile.next, generator.next so I ended up with :meth:`next` but it was still wrong. I've committed 51e11b4937b7 which uses :meth:`~file.next` instead, and it works. Cheers, -- Sandro Tosi (aka morph, morpheus, matrixhasu) My website: http://matrixhasu.altervista.org/ Me at Debian: http://wiki.debian.org/SandroTosi ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Hi, Le 14/01/2012 15:31, Sandro Tosi a écrit : On Sat, Jan 14, 2012 at 04:24, Éric Araujo wrote: Doc/glossary.rst:520: WARNING: unknown keyword: nonlocal That’s a mistake I did in cefe4f38fa0e. This sentence should be removed. Do you mean revert this whole hunk: [...] or just "The :keyword:`nonlocal` allows writing to outer scopes."? My proposal was to remove just that one last sentence, but the only other change in the diff hunk is the addition of “by default”, which is connected to the existence of nonlocal. Both changes, i.e. the whole hunk, should be reverted (I think I’ll have time to do that today). Doc/library/stdtypes.rst:2372: WARNING: more than one target found for cross-reference u'next': Need to use :meth:`.next` to let Sphinx find the right target (more info on request :) it seems what it needed to was :meth:`next` (without the dot). The current page links all 'next' in file.next() to functions.html#next, and using :meth:`next` does that. I should have given more info, as I wanted the opposite result :) file.next should not link to the next function but to the file.next method. Because Sphinx does not differentiate between meth/func/class/mod roles, :meth:`next` is not resolved to the nearest next method as one could expect but to the next function, so we have to use :meth:`~SomeClass.next` or :meth:`.next` (local ref markup) to get our links to methods. Doc/reference/datamodel.rst:1942: WARNING: unknown keyword: not in Doc/reference/expressions.rst:1184: WARNING: unknown keyword: is not Georg fixed them. Cheers ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
On Sat, Jan 14, 2012 at 04:24, Éric Araujo wrote: > Hi Sandro, > > Thanks for getting the ball rolling on this. One style for markup, one > Sphinx version to code our extensions against and one location for the > documenting guidelines will make our work a bit easier. thanks :) I'm happy to help! >> During the build process, there are some warnings that I can understand: > > I assume you mean “can’t”, as you later ask how to fix them. As a yes, indeed > general rule, they’re only warnings, so they don’t break the build, only > some links or stylings, so I think it’s okay to ignore them *right now*. but I like to get them fixed nonetheless: after all, the current build doesn't show warnings - but I agree it's a non-blocking issue. >> Doc/glossary.rst:520: WARNING: unknown keyword: nonlocal > > That’s a mistake I did in cefe4f38fa0e. This sentence should be removed. Do you mean revert this whole hunk: @@ -480,10 +516,11 @@ nested scope The ability to refer to a variable in an enclosing definition. For instance, a function defined inside another function can refer to - variables in the outer function. Note that nested scopes work only for - reference and not for assignment which will always write to the innermost - scope. In contrast, local variables both read and write in the innermost - scope. Likewise, global variables read and write to the global namespace. + variables in the outer function. Note that nested scopes by default work + only for reference and not for assignment. Local variables both read and + write in the innermost scope. Likewise, global variables read and write + to the global namespace. The :keyword:`nonlocal` allows writing to outer + scopes. new-style class Any class which inherits from :class:`object`. This includes all built-in or just "The :keyword:`nonlocal` allows writing to outer scopes."? >> Doc/library/stdtypes.rst:2372: WARNING: more than one target found for >> cross-reference u'next': > > Need to use :meth:`.next` to let Sphinx find the right target (more info > on request :) it seems what it needed to was :meth:`next` (without the dot). The current page links all 'next' in file.next() to functions.html#next, and using :meth:`next` does that. >> Doc/library/sys.rst:651: WARNING: unknown keyword: None > > Should use ``None``. fixed >> Doc/reference/datamodel.rst:1942: WARNING: unknown keyword: not in >> Doc/reference/expressions.rst:1184: WARNING: unknown keyword: is not > > I don’t know if these should work (i.e. create a link to the appropriate > language reference section) or abuse the markup (there are “not” and > “in” keywords, but no “not in” keyword → use ``not in``). I’d say ignore > them. ACK, but I'm willing to fix them if someone tells me how to :) I'm going to prepare the patches and then push - i'll send a heads-up afterward. Cheers, -- Sandro Tosi (aka morph, morpheus, matrixhasu) My website: http://matrixhasu.altervista.org/ Me at Debian: http://wiki.debian.org/SandroTosi ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Hi Sandro, Thanks for getting the ball rolling on this. One style for markup, one Sphinx version to code our extensions against and one location for the documenting guidelines will make our work a bit easier. During the build process, there are some warnings that I can understand: I assume you mean “can’t”, as you later ask how to fix them. As a general rule, they’re only warnings, so they don’t break the build, only some links or stylings, so I think it’s okay to ignore them *right now*. Doc/glossary.rst:520: WARNING: unknown keyword: nonlocal That’s a mistake I did in cefe4f38fa0e. This sentence should be removed. Doc/library/stdtypes.rst:2372: WARNING: more than one target found for cross-reference u'next': Need to use :meth:`.next` to let Sphinx find the right target (more info on request :) Doc/library/sys.rst:651: WARNING: unknown keyword: None Should use ``None``. Doc/reference/datamodel.rst:1942: WARNING: unknown keyword: not in Doc/reference/expressions.rst:1184: WARNING: unknown keyword: is not I don’t know if these should work (i.e. create a link to the appropriate language reference section) or abuse the markup (there are “not” and “in” keywords, but no “not in” keyword → use ``not in``). I’d say ignore them. Cheers ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Hi all, On Sat, Aug 27, 2011 at 07:47, Georg Brandl wrote: > One of the main reasons for keeping Sphinx compatibility to 0.6.x was to > enable distributions (like Debian) to build the docs for the Python they ship > with the version of Sphinx that they ship. > > This should now be fine with 1.0.x, so since you are ready to do the work of > converting the 2.7 Doc sources, it will be accepted. The argument of easier > backports is a very good one. Not exactly as quickly as I would, I started to work on upgrading sphinx for 2.7. Currently I've all the preliminary patches at: http://hg.python.org/sandbox/morph/shortlog/5057ce392838 in the 2.7-sphinx branch (they fix one thing at a time, they'll be collapsed once all ready). During the build process, there are some warnings that I can understand: writing output... [100%] whatsnew/index /home/morph/cpython/morph_sandbox/Doc/glossary.rst:520: WARNING: unknown keyword: nonlocal /home/morph/cpython/morph_sandbox/Doc/library/stdtypes.rst:2372: WARNING: more than one target found for cross-reference u'next': iterator.next, multifile.MultiFile.next, csv.csvreader.next, dbhash.dbhash.next, mailbox.oldmailbox.next, ttk.Treeview.next, nntplib.NNTP.next, file.next, bsddb.bsddbobject.next, tarfile.TarFile.next, generator.next /home/morph/cpython/morph_sandbox/Doc/library/stdtypes.rst:2372: WARNING: more than one target found for cross-reference u'next': iterator.next, multifile.MultiFile.next, csv.csvreader.next, dbhash.dbhash.next, mailbox.oldmailbox.next, ttk.Treeview.next, nntplib.NNTP.next, file.next, bsddb.bsddbobject.next, tarfile.TarFile.next, generator.next /home/morph/cpython/morph_sandbox/Doc/library/sys.rst:651: WARNING: unknown keyword: None /home/morph/cpython/morph_sandbox/Doc/library/sys.rst:712: WARNING: unknown keyword: None /home/morph/cpython/morph_sandbox/Doc/reference/datamodel.rst:1942: WARNING: unknown keyword: not in /home/morph/cpython/morph_sandbox/Doc/reference/expressions.rst:1101: WARNING: unknown keyword: not in /home/morph/cpython/morph_sandbox/Doc/reference/expressions.rst:1135: WARNING: unknown keyword: not in /home/morph/cpython/morph_sandbox/Doc/reference/expressions.rst:1176: WARNING: unknown keyword: not in /home/morph/cpython/morph_sandbox/Doc/reference/expressions.rst:1184: WARNING: unknown keyword: is not /home/morph/cpython/morph_sandbox/Doc/reference/expressions.rst:1362: WARNING: unknown keyword: is not /home/morph/cpython/morph_sandbox/Doc/reference/simple_stmts.rst:700: WARNING: unknown keyword: None /home/morph/cpython/morph_sandbox/Doc/reference/simple_stmts.rst:729: WARNING: unknown keyword: None /home/morph/cpython/morph_sandbox/Doc/reference/simple_stmts.rst:729: WARNING: unknown keyword: None writing additional files... genindex py-modindex search download index opensearch Do you know how I can fix them? Thanks & Cheers, -- Sandro Tosi (aka morph, morpheus, matrixhasu) My website: http://matrixhasu.altervista.org/ Me at Debian: http://wiki.debian.org/SandroTosi ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Am 23.08.2011 01:09, schrieb Sandro Tosi: > Hi all, > >> Any chance the version of sphinx used to generate the docs on >> docs.python.org could be updated? > > I'd like to discuss this aspect, in particular for the implication it > has on http://bugs.python.org/issue12409 . > > Personally, I do think it has a value to have the same set of tools to > build the Python documentation of the currently active branches. > Currently, only 2.7 is different, since it still fetches (from > svn.python.org... can we fix this too? suggestions welcome!) sphinx > 0.6.7 while 3.2/3.3 uses 1.0.7. > > If you're worried about the time needed to convert the actual 2.7 doc > to new sphinx format and all the related changes, I volunteer to do > the job (and/or collaborate with whom is already on it), but what I > want to understand if it's an acceptable change. > > I see sphinx more as of an internal, building tool, so freezing it > it's like saying "don't upgrade gcc" or so. Now the delta is just the > C functions definitions and some py-specific roles, but during the > years it will increase. Keeping it small, simplifying the forward-port > of doc patches (not needing to have 2 version between 2.7 and 3.x > f.e.) and having a common set of tools for doc building is worth IMHO. > > What do you think about it? and yes Georg, I'd like to hear your opinion too > :) One of the main reasons for keeping Sphinx compatibility to 0.6.x was to enable distributions (like Debian) to build the docs for the Python they ship with the version of Sphinx that they ship. This should now be fine with 1.0.x, so since you are ready to do the work of converting the 2.7 Doc sources, it will be accepted. The argument of easier backports is a very good one. The issue of using svn to download the tools is orthogonal; for this I would agree to just packaging up a tarball or zipfile that is then downloaded using a small Python script (should be properly cross-platform then). Cloning the original repositories is a) not useful, b) depends on availability of at least two additional servers (remember docutils) and c) requires hg and svn. Georg ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Wiadomość napisana przez Sandro Tosi w dniu 23 sie 2011, o godz. 01:09:What I want to understand if it's an acceptable change.I see sphinx more as of an internal, building tool, so freezing itit's like saying "don't upgrade gcc" or so.Normally I'd say it's natural for us to specify that for a legacy release we're using build tools in versions up to so-and-so. Plus, requiring changes in the repository additionally points that this is indeed touching "frozen" code.In case of 2.7 though, it's our "LTS release" so I think if Georg agrees, I'm also in favor of the upgrade.As for Sphinx using svn.python.org, the main issue is not altering the scripts to use Hg, it's the weight of the whole Sphinx repository that would have to be cloned for each distclean. By using SVN you're only downloading a specifically tagged source tree. -- Best regards,Łukasz LangaSenior Systems Architecture EngineerIT Infrastructure DepartmentGrupa Allegro Sp. z o.o.Pomyśl o środowisku naturalnym zanim wydrukujesz tę wiadomość!Please consider the environment before printing out this e-mail. ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Hi all, > Any chance the version of sphinx used to generate the docs on > docs.python.org could be updated? I'd like to discuss this aspect, in particular for the implication it has on http://bugs.python.org/issue12409 . Personally, I do think it has a value to have the same set of tools to build the Python documentation of the currently active branches. Currently, only 2.7 is different, since it still fetches (from svn.python.org... can we fix this too? suggestions welcome!) sphinx 0.6.7 while 3.2/3.3 uses 1.0.7. If you're worried about the time needed to convert the actual 2.7 doc to new sphinx format and all the related changes, I volunteer to do the job (and/or collaborate with whom is already on it), but what I want to understand if it's an acceptable change. I see sphinx more as of an internal, building tool, so freezing it it's like saying "don't upgrade gcc" or so. Now the delta is just the C functions definitions and some py-specific roles, but during the years it will increase. Keeping it small, simplifying the forward-port of doc patches (not needing to have 2 version between 2.7 and 3.x f.e.) and having a common set of tools for doc building is worth IMHO. What do you think about it? and yes Georg, I'd like to hear your opinion too :) Cheers, -- Sandro Tosi (aka morph, morpheus, matrixhasu) My website: http://matrixhasu.altervista.org/ Me at Debian: http://wiki.debian.org/SandroTosi ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
On Wed, Aug 17, 2011 at 12:08 PM, Chris Withers wrote:
> On 16/08/2011 16:05, Sandro Tosi wrote:
>> I think what's needed first is to run a pilot: take the current 2.7
>> doc,
>
> Where does that live?
> Where are the instructions for building the docs? (dependencies needed, etc)
'make html' in the Docs directory of a CPython checkout ("hg clone
http://hg.python.org/cpython";) usually does the trick.
See http://docs.python.org/dev/documenting/building.html for more
detail if the above doesn't work.
Cheers,
Nick.
--
Nick Coghlan | ncogh...@gmail.com | Brisbane, Australia
___
Python-Dev mailing list
Python-Dev@python.org
http://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
On 16/08/2011 16:05, Sandro Tosi wrote: Hello Chris, On Wed, Aug 17, 2011 at 00:58, Chris Withers wrote: Hi All, Any chance the version of sphinx used to generate the docs on docs.python.org could be updated? I think what's needed first is to run a pilot: take the current 2.7 doc, Where does that live? Where are the instructions for building the docs? (dependencies needed, etc) cheers, Chris -- Simplistix - Content Management, Batch Processing & Python Consulting - http://www.simplistix.co.uk ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] Sphinx version for Python 2.x docs
Hello Chris, On Wed, Aug 17, 2011 at 00:58, Chris Withers wrote: > Hi All, > > Any chance the version of sphinx used to generate the docs on > docs.python.org could be updated? I think what's needed first is to run a pilot: take the current 2.7 doc, update sphinx and look at what breaks, and evaluate if it's fixable in a reasonable amount of time, or it's just too much and so on. Currently no-one has done that yet: would you ? :) That would helps up quite much Cheers, -- Sandro Tosi (aka morph, morpheus, matrixhasu) My website: http://matrixhasu.altervista.org/ Me at Debian: http://wiki.debian.org/SandroTosi ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
