[Python-Dev] Sphinx version for Python 2.x docs

[Sandro Tosi]

On Sat, Jan 14, 2012 at 04:24, Éric Araujo <merwok at netwok.org> 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