gmane.comp.python.documentation

Style guide for documentation

Benoît Bryon — 2012-05-14T07:46:08

Hi,

I am posting this message on docutils-users, sphinx-dev and doc-sig
mailing lists:

* < at >docutils-users, it's a proposal about some "restrictive"
  reStructuredText subset;
* < at >sphinx-dev, it's about Sphinx usage, i.e. best practices;
* < at >doc-sig, I wonder if it could be a PEP for documentation of Python
  packages.


I started to write down conventions for Sphinx-based documentations at
https://github.com/benoitbryon/documentation-style-guide-sphinx

I'd like to share this work, and I also need feedback.
I guess it could be compared to PEP-8, as a "style guide", but applied
to Sphinx-based documentations.
Python code can be valid even if it doesn't follow PEP-8; but Python
code should follow PEP-8 because it's the convention (and de facto best
practice).

More explanations below.


Story
=====

As a developer, I started using Sphinx some years ago. I contributed to
documentation of public or private projects using Sphinx. I also worked
in several teams with different background:

* private projects with Py

Re: self on built-in functions

Michael Foord — 2012-02-13T17:40:57

Yep, that seems like a documentation bug. Please file an issue for it.

All the best,

Michael

self on built-in functions

Роман Донченко — 2012-02-13T16:43:47

Hello,

The language reference for Python 3.2 (and the development version, as  
well), says this in section 3.2:

~
Built-in functions

A built-in function object is a wrapper around a C function. Examples of  
built-in functions are len() and math.sin() (math is a standard built-in  
module). <...> Special read-only attributes: <...> __self__ is set to None  
(but see the next item) <...>.
~

Now I don't know whether it's a bug in Python or in the docs, but that  
doesn't seem to be the case:

ActivePython 3.2.2.3 (ActiveState Software Inc.) based on
Python 3.2.2 (default, Sep  8 2011, 10:55:13) [MSC v.1500 64 bit (AMD64)]  
on win32
Type "help", "copyright", "credits" or "license" for more information.
<module 'builtins' (built-in)>
<module 'io' (built-in)>
<module 'math' (built-in)>

Thoughts?

Roman.

_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Could anyone update pootle.python.org?

INADA Naoki — 2011-12-26T08:27:00

Hi, all.

I am a Japanese translator of Python Documentation.
Our team have released Japanese Python 2.7.2 Document on 12/25.
 http://www.python.jp/doc/2.7/

Then, I thinking about how to translate Python 3 Document.
I want to use sphinx-i18n, but I need to setup pootle or another i18n
site to make it able to
try sphinx-i18n.

I see http://pootle.python.org/ , but it is too old.
Could anyone update pootle and pot generated by newest Sphinx and Python?

Re: PEP 258

David Goodger — 2011-04-20T23:59:25

PEP 258's "Rejection Notice" states: "While this may serve as an
interesting design document for the now-independent docutils, it is no
longer slated for inclusion in the standard library." While relevant
to Docutils, PEP 258 is simply not relevant to Python the language or
Python's standard library.

As for PEP 256, it has effectively been implemented in Sphinx, which
uses Docutils.

Both projects are have been implemented, but outside of the standard
library, and that's just fine. When I wrote the PEPs I had the goal of
standard library inclusion, but that proved not to be so important.
Thanks to its own merits, some small initial nudges from me (like
proposing reST as a markup for PEPs themselves), and the efforts of
many people, Docutils & reStructuredText have become a standard in the
Python world.

PEP 258

Greg Scaffidi — 2011-04-20T22:31:47

Hello,

I am working on a project for my Masters' Verification & Validation class.  The 
topic of the project is to explore the possibilities of implementing a modeling 
language for Python that supports Design-by-Contract and Unit-testing.  In my 
research, I came across the Docutils project.  I was wondering why the project 
was rejected from the PEP.  I also noticed that the Docstring Processing System 
Framework (PEP-256), was also rejected.  The reason given for the rejection of 
PEP-256 is that, "Proposal seems to have run out of steam."  Since PEP-256 
serves as a, "Rationale" for PEP-258, I was also wondering if PEP-258 was 
rejected for the same reason.  Both projects seem like worthy pursuits.  What 
other reasons, if any, are there for rejecting them?

Thank you very much for your help.

Sincerely

- Greg Scaffidi_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Re: Python tutorial

Aahz — 2011-04-07T03:23:53

If you're looking for feedback, you'll likely get better responses from
comp.lang.python

Re: Python tutorial

Robert Lehmann — 2011-04-06T13:56:22

Hi Guido,

have you had a look at the official tutorial [1]_ and the Using Python
[2]_ guides?  If so, what did you find particularly lacking about
them?  We are always open for suggestions and happy to improve!  (I'm
keeping this on-list purposefully for these questions;  we usually
discuss the *Python* documentation here, but we're quite low-traffic
anyways, so..)

.. [1] http://docs.python.org/tutorial/
.. [2] http://docs.python.org/using/

All the best,
Robert

PS.  You need to tweak the styling:  the links should stand out a
little more and code needs to be monospaced.  I am quite a fan of
linking to external resources, too, which would give your readers a
better starting point.


On Sun, Apr 3, 2011 at 6:04 AM, Guido Carballo-Guerrero <charras< at >me.com> wrote:
_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Python tutorial

Guido Carballo-Guerrero — 2011-04-03T04:04:29

I just start writing a tutorial about Python, and will like to share it with you guys. It's a project that I just start, so any comment is very much appreciated:

http://web.me.com/charras/Python/Welcome.html

Guido Carballo
_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Re: Shouldn't tutorial follow the pep8?

INADA Naoki — 2011-03-07T05:45:40

I've make a patch and post it to http://bugs.python.org/issue11425

On Mon, Mar 7, 2011 at 7:56 AM, Michael Foord <fuzzyman< at >voidspace.org.uk> wrote:

Re: Does the "is" operator only matter for mutable object?

Fred Drake — 2011-03-07T04:12:38

It's important because Python promises that None is a singleton at the
language level, rather than the implementation level.  That's
different than using cached values of small integers, since that's a
runtime efficiency issue (and therefore implementation specific).

That's essential to the recommended practice of testing for None using
"is" rather than "=="; it's irrelevant to the general description of
"is".


  -Fred

--
Fred L. Drake, Jr.    <fdrake at acm.org>
"A storm broke loose in my mind."  --Albert Einstein
_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Re: Does the "is" operator only matter for mutable object?

Fred Drake — 2011-03-07T04:09:33

That still seems too complicated.  Pointing out that equality does not
imply identity, regardless of type, should be sufficient for the
purpose of describing "is".


  -Fred

--
Fred L. Drake, Jr.    <fdrake at acm.org>
"A storm broke loose in my mind."  --Albert Einstein
_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Re: Does the "is" operator only matter for mutable object?

Laura Creighton — 2011-03-07T01:29:51

Good point.  Indeed, that may be where people who write code like that
get the idea.  I've always wondered.

Ok.

Change to:

Testing the object identity of unmutable objects with the ``is``
or ``is not`` operators is rarely something you want to do, because the
result is implementation dependent.  But the canonical way to test
whether an object is None is to test for object identity, not equality.

so

    ... do something ...

not

    ... do something ...

-----------
I figure that the fact that None is a singleton is not actually relevant
to this.

Laura
_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Re: Does the "is" operator only matter for mutable object?

Nick Coghlan — 2011-03-07T00:30:08

Careful with that - "if x is True:" and "if x is False:" (along with
s/is/==/) are almost always the wrong thing to do, but a reader could
easily generalise the above to cover those two cases as well.

Cheers,
Nick.

Re: Does the "is" operator only matter for mutable object?

Laura Creighton — 2011-03-06T23:28:24

<snip>

oops, that one escaped before I was done. 

The other point was that I wondered about the section title itself.
5.8. Comparing Sequences and Other Types

This reads as if we are comparing types, when that is not what this
section is about at all.

Laura
_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

Re: Does the "is" operator only matter for mutable object?

Laura Creighton — 2011-03-06T23:08:38

I've been doing more thinking, and I think the problem is more deeply 
rooted than this.

  From the original doc:


This is actually wrong.  If x is y, then you _aren't_ comparing two
objects, you are comparing one object with itself, and that is the
whole point.  You are comparing two names, and seeing if they are
bound to the same object.  What I really want to tell the perplexed
to do is read: http://effbot.org/zone/python-objects.htm  However:

Given that this is in the section on comparing sequences and other
types:

The operators ``is`` and ``is not`` test for object identity.  If two
different names are bound to the same object, then they compare the
same:  ``x is y`` .  

True
[1, 2, 3, 4]
[1, 2, 3, 4]

Confusion arises because implementors are free to cache immutable objects
with the same value and type to the same object for reasons of efficiency.

[PyPy 1.4.1] 
Type "help", "copyright", "credits" or "license" for more information.

False

Python 2.6.6 #(I don't have a 3.x around , I assume it wor

Re: Shouldn't tutorial follow the pep8?

Michael Foord — 2011-03-06T22:56:53

I believe a patch to the tutorial bringing it inline with pep 8 would be 
accepted (and a good thing).

All the best,

Michael

Shouldn't tutorial follow the pep8?

INADA Naoki — 2011-03-06T22:28:46

In http://docs.python.org/py3k/tutorial/classes.html#random-remarks


Capitalizing methd names doesn't follows pep8.

Many sample codes in tutorial doesn't follow pep8 too.
For example, in http://docs.python.org/py3k/tutorial/introduction.html#numbers
there are no spaces next to operators.

Re: Does the "is" operator only matter for mutable object?

Laura Creighton — 2011-03-06T00:45:32

<snip>

While the point is well taken that objects that are the same do not
have to occupy the same memory location, and don't in PyPy, the
problem with explaining the 'is' and 'is not' operator is explaining
what 'is the same object' means.

I think the greatest cause of confusion is the fact that Cpython interns
the intergers.  Thus:

[GCC 4.4.5] on linux2
Type "help", "copyright", "credits" or "license" for more information.
True
True


while:
Python 2.5.2 (e503e483e9ac, Dec 21 2010, 12:02:29)
[PyPy 1.4.1] on linux2
Type "help", "copyright", "credits" or "license" for more information.
And now for something completely different: ``dystopian and utopian chairs''
True
False

------------------

So maybe what we need to do is to explictly state that some implementations
have chosen to represent objects which are equivalent as the exact same
object, but that you should not rely on this behaviour because it is
an implementation detail?

Laura




_______________________________________________
Doc-SIG maillist

Re: Does the "is" operator only matter for mutable object?

Steven D'Aprano — 2011-03-05T23:59:55



Please remove the bit about the same memory location. That is an 
implementation detail which may be true for CPython, it may even be true 
for any sensible implementation of Python, but it's surely not a 
necessary condition for any language calling itself Python. I don't 
think it adds any clarity, since "same object" is a more intuitive 
concept than memory location (even non-programmers understand what it 
means to say that "my car" and "the car parked in the driveway" are the 
same object). And memory location is not something that Python the 
language exposes to the caller. Implementations with moving garbage 
collectors, such as PyPy and (I think) Jython, may move objects. All in 
all, I believe that Python's docs should stay as far away from any 
discussion of memory addresses as possible.

It might be obvious to English speakers that ``is`` and ``is not`` do 
the opposite, but as it stands above, the documentation suggests that 
they are two different ways of writing the same thing.

None, True a

Re: Does the "is" operator only matter for mutable object?

Elva Castaneda de Hall — 2011-03-05T19:16:08

Hello!
I am not sure how I ended up with a subscription to this virtual  
conversation. I am not even sure where to go to unsubscribe.

Rest assured I have no clue what is being discussed here.  ; > )

Can someone tell me the website URL I can go to unsubscribe?

Thanks, e

On Mar 5, 2011, at 11:12 AM, Laura Creighton wrote:


_______________________________________________
Doc-SIG maillist  -  Doc-SIG< at >python.org
http://mail.python.org/mailman/listinfo/doc-sig

gmane.comp.python.documentation

Style guide for documentation

Re: __self__ on built-in functions

__self__ on built-in functions

Could anyone update pootle.python.org?

Re: PEP 258

PEP 258

Re: Python tutorial

Re: Python tutorial

Python tutorial

Re: Shouldn't tutorial follow the pep8?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: Shouldn't tutorial follow the pep8?

Shouldn't tutorial follow the pep8?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: Does the "is" operator only matter for mutable object?

Re: self on built-in functions

self on built-in functions