http://blog.gmane.org/gmane.comp.python.documentation hourly 1 1901-01-01T00:00+00:00 http://gmane.org/img/gmane-25t.png http://gmane.org http://comments.gmane.org/gmane.comp.python.documentation/1532 <pre>Hi, I am posting this message on docutils-users, sphinx-dev and doc-sig mailing lists: * &lt; at &gt;docutils-users, it's a proposal about some "restrictive" reStructuredText subset; * &lt; at &gt;sphinx-dev, it's about Sphinx usage, i.e. best practices; * &lt; at &gt;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 Python developers working in the same company: * Python projects * PHP projects (yes, Sphinx is great to document a project, even if is not a Python project) * public projects, with people I didn't know before. I feel we lack some restrictive convention: * in each team, RST usage differ. As an example, one team choose .rst extension (sphinx-quickstart's default), whereas another choose .txt (docutils recommendation). * often, RST usage differ within documents of a project, depending on the original author: one developer uses "=" for first level of sections whereas another uses "-" symbol. * and many more use cases... * as a new contributor, when I joined a project or team, I spent too much time discovering conventions of the project. About documentation, I had to read current project's documentation, and often there was no convention at all. * when I tried to propose conventions in a team, we had discussions. Again it's time we'd better spend on development than on discussion. I mean it's important to discuss and to share vision, but for this particular topic we should have used an existing convention, we shouldn't have asked. * when I proposed the convention from one team to another, we discussed it again. With other argues, and potentially a different convention at the end :'( That's why I started to write down conventions in a collaborative place, so that every team can use it, reference it and contribute to it: https://github.com/benoitbryon/documentation-style-guide-sphinx Key features ============ * more restrictive than reStructuredText: as told by the Zen of Python, "There should be one-- and preferably only one --obvious way to do it." * focus on use case: Sphinx-based documentation for a project. As an example, use Sphinx's specific directives. * provide more than just syntax. As an example, recommend usage of target-notes directive at the end of a document, instead of using inline hyperlinks. Feedback required ================= * I wonder whether such conventions already exist or not. * I wonder whether I should maintain a standalone convention or contribute to Docutils, Sphinx or even Python via a PEP... In fact, I guess I'd rather contribute, but I am not sure... * maybe reStructuredText documentation could include some of the proposed conventions as recommendations, so that users naturally use these conventions. * maybe Sphinx documentation could recommend some points in its reStructuredText primer. * maybe a PEP could recommend every Python developer to follow some style guide when they write Sphinx documents. * ... other suggestions are welcome! * if you are interested in the project, use it or open issues! Regards, -- Benoit Bryon _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Benoît Bryon 2012-05-14T07:46:08 http://comments.gmane.org/gmane.comp.python.documentation/1530 <pre>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). &lt;...&gt; Special read-only attributes: &lt;...&gt; __self__ is set to None (but see the next item) &lt;...&gt;. ~ 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. &lt;module 'builtins' (built-in)&gt; &lt;module 'io' (built-in)&gt; &lt;module 'math' (built-in)&gt; Thoughts? Roman. _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Роман Донченко 2012-02-13T16:43:47 http://comments.gmane.org/gmane.comp.python.documentation/1529 <pre>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? </pre> INADA Naoki 2011-12-26T08:27:00 http://comments.gmane.org/gmane.comp.python.documentation/1527 <pre>Hello, I am working on a project for my Masters' Verification &amp; 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&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Greg Scaffidi 2011-04-20T22:31:47 http://comments.gmane.org/gmane.comp.python.documentation/1524 <pre>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&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Guido Carballo-Guerrero 2011-04-03T04:04:29 http://comments.gmane.org/gmane.comp.python.documentation/1515 <pre>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. </pre> INADA Naoki 2011-03-06T22:28:46 http://comments.gmane.org/gmane.comp.python.documentation/1505 <pre>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 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? </pre> INADA Naoki 2011-03-05T02:19:52 http://comments.gmane.org/gmane.comp.python.documentation/1486 <pre>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 &lt; at &gt;precondition/&lt; at &gt;postcondition/&lt; at &gt;type/&lt; at &gt;rtype docstring fields in every function wrapped using &lt; at &gt;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 &lt; at &gt;contract_epydoc decorator to wrap the classes, thus making possible to add the support of &lt; at &gt;invariant fields in the class docstrings. </pre> Alex Myodov 2010-11-09T13:09:48 http://comments.gmane.org/gmane.comp.python.documentation/1478 <pre>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&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Bill Janssen 2010-10-06T16:52:15 http://comments.gmane.org/gmane.comp.python.documentation/1475 <pre>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 "&lt;" on left end and "&gt;" on right end? In the code: def canonic(self, filename): if filename == "&lt;" + filename[1:-1] + "&gt;": 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 "&lt;" and "&gt;". </pre> INADA Naoki 2010-09-02T06:24:34 http://comments.gmane.org/gmane.comp.python.documentation/1471 <pre>Dear Python Documentation community, we are proud to announce the *BETA* launch of the translation services for the official Python documentation as part of Google's Summer of Code. It is available from http://pootle.python.org/ and is open for registration now. We have added a few languages that we felt would generate enough feedback but are always happy to add more language teams. Please note that the software toolchain used to create this service is still experimental and might probably change substantially. We are trying our best to maintain stable services but cannot guarantee every bit you submit will be ultimately usable in our final translation targets. If you are experiencing any trouble, want to bring up any suggestions or have other feedback do not hesitate to contact me or file a ticket at http://bitbucket.org/lehmannro/sphinx-i18n/issues Robert Lehmann _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Robert Lehmann 2010-07-07T08:06:27 http://comments.gmane.org/gmane.comp.python.documentation/1468 <pre>_______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Jonas Lindberg 2010-06-04T11:39:11 http://comments.gmane.org/gmane.comp.python.documentation/1466 <pre>Random thoughts on the Generic Operating System Services chapter of the library guide: http://docs.python.org/dev/library/allos.html * There are four sections that are very long and complex, nesting down to four levels: argparse, optparse, logging, and ctypes. Should any of them become chapters of their own? logging and ctypes seem like the most plausible ones to move. We could move argparse/optparse/getopt into a chapter by themselves, but that wouldn't reduce the nesting depth at all. * The usual rationale for the ordering is from more widely used modules to more esoteric or little-used. Should we therefore move optparse to follow getopt instead of preceding it? * I thought we were going to add a warning to the optparse docs suggesting people use argparse instead. Shall I go ahead and write that, or was it decided to not do that? --amk _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> A.M. Kuchling 2010-05-12T14:44:15 http://comments.gmane.org/gmane.comp.python.documentation/1459 <pre>Hi, all. I am one of translator of Python document. But I am not good at English well. I can't understand one sentence in: http://docs.python.org/library/difflib.html#difflib.SequenceMatcher.quick_ratio I see that quick_ratio() calculates upper bound of ratio(). But I can't get what "this isn't defined beyond that" means. May someone explain this in easy sentence for me? </pre> INADA Naoki 2010-05-06T14:48:22 http://comments.gmane.org/gmane.comp.python.documentation/1413 <pre>_______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Barry Warsaw 2010-04-13T21:12:19 http://comments.gmane.org/gmane.comp.python.documentation/1405 <pre> The procedure for uploading to PyPI is not well documented. I had to read several different docs and do some experimentation before coming up with the following: Procedure for uploading to the Python Package Index (PyPI): 1. Create setup.py file. 2. Create ".pypirc" file if it does not already exist. 3. Launch IPython. 4. Issue the command "run setup register" 5. Issue the command "run setup sdist upload". 6. Log into PyPI and adjust visibility of old versions as necessary. I'd like to see this list of steps (or something similar) in the docs. </pre> Dr. Phillip M. Feldman 2009-12-11T18:05:07 http://comments.gmane.org/gmane.comp.python.documentation/1404 <pre> Hi, just updated this patch so it works with Python version 3.2. http://bugs.python.org/issue2001 What it does is add a navigation bar at the top of the web pages so you can do the following. + Shows what version of python you are browsing/using. + Get an item - It takes the same input as the help() function does in the console. + Search - Returns the same result as the tkinter search box. + Module index - The normal default top level. + Topics - lists all the topics. They can be clicked on and the results are displayed with xrefs that can be clicked on. + Keywords - Lists all the keywords. Works the same as Topics. Also the file links are read in as text and served as a pydoc page instead of relying on the browsers file reading capability. That is much safer and gives a better file listing. This patch removes the tkinter search bar sense it's no longer needed. tkinter is no longer needed for pydoc to run in gui mode. It really makes browsing pythons library a breeze. If someone can try it out and give me some additional feedback as to possibly any problems or any changes I need to make it would be nice. Thanks, Ron Adam _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Ron Adam 2010-03-02T04:45:22 http://comments.gmane.org/gmane.comp.python.documentation/1401 <pre>Good morning, Release 0.6 is out. Changes are : * Two new writers for ODT and manpage (so there is no excuse for python software not having a manpage anymore). * Python2.2 is no longer supported. Release 0.6 is compatible with Python versions from 2.3 up to 2.6 and convertible to 3.1 code. * The "newlatex" writer is orphaned. * The LaTeX2e writer sports templates now and is the most active worked on part. There might be some suprises due to new defaults, but we tried to minimize breakage and choose sensible defaults. * The HTML writer supports a comma separated list of stylesheets. * Some changes to reStructuredText many thanks to all contributors. have a nice start into a new week. engelbert _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> grubert< at >users.sourceforge.net 2009-10-12T06:55:42 http://comments.gmane.org/gmane.comp.python.documentation/1400 <pre>Hi everyone! I'm new to the Python volunteer community, and another member suggested that helping out with documentation is a great way to get started. A bit of background on me: I'm a journalist who recently made the shift to full-time database work for Congressional Quarterly, a news organization based in Washington, D.C. I started dabbling with Python two years ago, and now have the good fortune to use it daily in my work. Python and its community have helped me enormously, so I figured it's time to give something back. I've started reading the style guide for documentation writers, but I wasn't able to dig up a list of projects or priorities that need doing. Is there such a list? If not, should we start one on the doc-sig page of the Python wiki? http://www.python.org/community/sigs/current/doc-sig/ For me, such a list would help focus my efforts on the genuine needs of the community. And it could help others who'd like to contribute but are not sure where to begin. So please let me know what you think about the idea of a priority list, or better yet, reply back with specific project ideas or needs. And of course, if such a list already exists, just point me to it. I'll be happy to help out. Regards, Serdar Tumgoren _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> Serdar Tumgoren 2009-10-11T16:34:55 http://comments.gmane.org/gmane.comp.python.documentation/1395 <pre>I'm writing an introduction to releasing open-source Python projects. Having recently gone through it for the first time myself, I was amazed at how far and wide I had to range to pull together all the information that goes into making a good Python package.  So I thought I'd write it up and share: http://infinitemonkeycorps.net/docs/pph/ It's tentatively called the "Python Project Howto," and it's aimed at people who, though not necessarily new to Python, may be new to packaging and possibly open source. It tries to be succinct and practical, demonstrating by example.  It covers choosing project hosting, setting up version control (Subversion basics), code quality (Pylint) and style (PEP 8), documentation (reStructuredText, Sphinx), unit testing (doctest and unittest), licensing, packaging (distutils), and release (PyPI). One thing I don't want it to be is an exhaustive list of all the possibilities for each of those areas.  For instance, I cover reStructuredText and Sphinx, but not epydoc; distutils but not setuptools. I've tried to pick the simplest, most common among several options, and sometimes provided a link to others (pip, nose). I'm trying to Keep It Simple for people just dipping their toes into the Python ecosystem.  I'd really like to know what people think; it would be great to get some feedback on it. Thanks! -John _______________________________________________ Doc-SIG maillist - Doc-SIG&lt; at &gt;python.org http://mail.python.org/mailman/listinfo/doc-sig </pre> John Kleint 2009-09-24T23:15:22 Search the mailing list at Gmane query http://search.gmane.org/?group=$group=gmane.comp.python.documentation