[CentralOH] Sphinx

[Yung-Yu Chen]

On Wed, Nov 11, 2009 at 13:30, James - Atlantix <james at atlantixeng.com>wrote:

>  Yung-Yu;
>
>
>
> Thanks for the feedback. I looked at the website for epydoc and it seems
> somewhat straight forward to use. I notice the epydoc has variable
> docstrings delineated by “ #:”
>
>
I have never added docstrings for variables inside a function/method.  I am
sorry that I am not sure what do you mean by variable docstrings.

With epytext (the default markup in epydoc), I usually put document for
class and/or instance variables in the docstrings for the class definition.
Docstrings for function/method arguments (param) and/or keywords are also
useful to me.

>
>
> Can you comment on how “cluttered” or “clean” your Python source code is
> when you add all the docstrings? I am pretty strict not overburdening the
> source code with too much documentation.
>
>
>
Since I've never put dosctrings "inside" the body of functions/methods, my
source code is very clean.  I guess I can have a good score in pylint :-)

yyc

> Thanks,
>
>
> James
>
>
>
> *From:* Yung-Yu Chen [mailto:yungyuc at gmail.com]
> *Sent:* Monday, November 09, 2009 2:24 PM
> *To:* James - Atlantix
> *Cc:* Catherine Devlin; centraloh at python.org
> *Subject:* Re: [CentralOH] Sphinx
>
>
>
> On Mon, Nov 9, 2009 at 14:11, James - Atlantix <james at atlantixeng.com>
> wrote:
>
> I am just basically looking at how to use Sphinx to document a Python
> project . . . so that others at my company can use modules I develop.
> Perhaps I should have used something different than sprint. . . a
> walkthrough on using Sphinx. I have read articles, but they are a bit large
> on information.
>
>
>
>
> For internal projects, I usually prefer to write API doc using epydoc
> rather than write book-style documentation with sphinx.  Full-fledged
> documentation is too heavy-weight to my projects, and readers are too
> limited.  API doc is more suitable to my need.
>
> Just my 2 cents.
>
> with regards,
> Yung-Yu Chen
>
>
>  Thanks,
>
>
>
> James
>
>
>
> *From:* Catherine Devlin [mailto:catherine.devlin at gmail.com]
> *Sent:* Monday, November 09, 2009 2:03 PM
> *To:* James - Atlantix
> *Cc:* centraloh at python.org
> *Subject:* Re: [CentralOH] Sphinx
>
>
>
> I have - though it's the sort of Python project that really isn't intended
> for developer-level use (an end user uses the product overall, they don't
> import the module and then invoke specific functions or classes from it).
> But anyway, sqlpython's docs are in Sphinx:
> http://pypi.python.org/pypi/sqlpython
>
> Can you explain what you mean by a sprint in this context?  (I only know
> sprints as code-writing exercises, and I assume you don't mean we should
> write new code for Sphinx...)
>
> On Mon, Nov 9, 2009 at 12:11 PM, James - Atlantix <james at atlantixeng.com>
> wrote:
>
> I am wondering if anyone has experience documenting a Python project with
> Sphinx? If so, would they be willing to do a sprint at the next meeting?
>
>
> Thanks,
>
> James
>
>
> _______________________________________________
> CentralOH mailing list
> CentralOH at python.org
> http://mail.python.org/mailman/listinfo/centraloh
>
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/mailman/private/centraloh/attachments/20091111/37619313/attachment.htm>