headers
Benoît Bryon | 14 May 09:46
Gravatar

Style guide for documentation

Hi,

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

* @docutils-users, it's a proposal about some "restrictive"
  reStructuredText subset;
* @sphinx-dev, it's about Sphinx usage, i.e. best practices;
* @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:
(Continue reading)

Permalink | Reply | 0 comments |
headers
Роман Донченко | 13 Feb 17:43
Picon
Favicon

__self__ on built-in functions

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.
>>> len.__self__
<module 'builtins' (built-in)>
>>> open.__self__
<module 'io' (built-in)>
>>> import math
>>> math.sin.__self__
<module 'math' (built-in)>

Thoughts?
(Continue reading)

Permalink | Reply | 1 comment |
headers
INADA Naoki | 26 Dec 09:27
Picon

Could anyone update pootle.python.org?

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?

--

-- 
INADA Naoki  <songofacandy <at> gmail.com>
_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 0 comments |
headers
Greg Scaffidi | 21 Apr 00:31
Picon
Favicon

PEP 258

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 y our help.

Sincerely

- Greg Scaffidi
_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 1 comment |
headers
Guido Carballo-Guerrero | 3 Apr 06:04

Python tutorial

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
Permalink | Reply | 2 comments |
headers
INADA Naoki | 6 Mar 23:28
Picon

Shouldn't tutorial follow the pep8?

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

> Possible conventions include capitalizing method names, prefixing
> data attribute names with a small unique string (perhaps just an underscore),
> or using verbs for methods and nouns for data attributes.

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.

--

-- 
INADA Naoki  <songofacandy <at> gmail.com>
_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 2 comments |
headers
Steven D'Aprano | 5 Mar 04:13

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

INADA Naoki wrote:
> In
> http://docs.python.org/py3k/tutorial/datastructures.html#comparing-sequences-and-other-types
> ,
> 
> The operators is and is notcompare whether two objects are really the same
>> object;
>> this only matters for mutable objects like lists.
> 
> 
> I think this notation may confuse readers of the tutorial. For example, pep8
> recommands
> using is operator for immutable singleton objects like None.
> 
> Shall we remove letter part?

Rather than completely remove it, I would reword it:

The operators is and is not compare whether two objects are really the 
same object; this usually only matters for mutable objects like lists, 
or for testing against singletons like None.

--

-- 
Steven

_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 14 comments |
headers
INADA Naoki | 5 Mar 03:19
Picon

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

In http://docs.python.org/py3k/tutorial/datastructures.html#comparing-sequences-and-other-types, 

The operators is and is notcompare whether two objects are really the same object;
this only matters for mutable objects like lists.

I think this notation may confuse readers of the tutorial. For example, pep8 recommands
using is operator for immutable singleton objects like None.

Shall we remove letter part?
--
INADA Naoki  <songofacandy <at> gmail.com>

_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 0 comments |
headers
Alex Myodov | 9 Nov 14:09
Picon

python-dbc (epydoc-based Design-by-Contract validator)

Hello,

I would like to notify the community about the availability of new python-dbc module, allowing one to perform basic design-by-contract checks using the docstring definitions in epydoc format. No public releases has been done yet, but the home page with overall instructions is created at http://python-dbc.googlecode.com/ and the code is available at https://python-dbc.googlecode.com/hg/ (this is a Mercurial repository, use hg clone).

At the moment, the primary functionality available is the validation of <at> precondition/ <at> postcondition/ <at> type/ <at> rtype docstring fields in every function wrapped using <at> contract_epydoc decorator. The code is early, lacks a proper amount of unit tests and documentation, and definitely may have bugs for now, but it is stress-tested at the moment in internal projects, so far so good. The future plans include allowing to use the <at> contract_epydoc decorator to wrap the classes, thus making possible to add the support of <at> invariant fields in the class docstrings.

--
With best regards,
  Alexander Myodov
email: amyodov <at> gmail.com
My LinkedIn page,enMoiKrug page,ruLiveJournal blogru 
_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 0 comments |
headers
Bill Janssen | 6 Oct 18:52
Favicon

alternatives to epydoc?

I've been documenting UpLib with a combo of ReST for the standalone
docs, and epydoc for the API documentation.  But epydoc seems to be
dying a slow death of non-maintenance.  It won't work with docutils 0.6
or 0.7, and Python 2.6 seems to crash when running it.

So, I'm looking for an alternative to epydoc.  Preferably something
easy to convert to...  Any pointers?

Bill
_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 7 comments |
headers
INADA Naoki | 2 Sep 08:24
Picon

bdb.Bdb.canonic() -- What "stripped of surrounding angle brackets" means?

Hi, all.

on http://docs.python.org/library/bdb.html

  canonic(filename)
  Auxiliary method for getting a filename in a canonical form, that
is, as a case-normalized
  (on case-insensitive filesystems) absolute path, stripped of
surrounding angle brackets.

Is " stripped of surrounding angle brackets." means it removes "<" on
left end and ">" on right end?
In the code:

    def canonic(self, filename):
        if filename == "<" + filename[1:-1] + ">":
            return filename
        canonic = self.fncache.get(filename)
        if not canonic:
            canonic = os.path.abspath(filename)
            canonic = os.path.normcase(canonic)
            self.fncache[filename] = canonic
        return canonic

canonic() doesn't remove "<" and ">".

--

-- 
INADA Naoki  <songofacandy <at> gmail.com>
_______________________________________________
Doc-SIG maillist  -  Doc-SIG <at> python.org
http://mail.python.org/mailman/listinfo/doc-sig
Permalink | Reply | 2 comments |

Gmane