Re: [sphinx-users] automodule and module-level docstrings

[Takayuki Shimizukawa]

Hi Thomi,

I got the result that you expected with bot Sphinx-1.1.3 and 1.2b1.
Did you solve your problem yet?

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa


2013/4/8 Thomi Richards <tho...@gmail.com>:
> Hi everyone,
>
>
> I'm using sphinx to document a python project of mine. I've run into a
> problem with the automodule directive - it seems to ignore module-level
> docstrings. For example:
>
> in module.py:
>
> <code>
>
> """
> My Module
> #########
>
> General introductory text to this module - links to classes & functions
> defined in the module go here.
>
> """
>
> def a_function():
> """some docstring for a_function."""
>
>
> class Foo(object):
> """Some docstring for Foo."""
>
> </code>
>
>
> in my sphinx documentation files, I have:
>
> <code>
> .. automodule:: module
> :members:
> </code>
>
>
> What I expect to see in the output is something similar to:
> <output>
> <heading>My module</heading>
>
> General introductory text to this module - links to classes & functions
> defined in the module go here.
>
> documentation for 'a_function'
>
> documentation for 'Foo'
> </output>
>
>
> Instead, I just get the documentation for the functions & classes defined in
> that module.
>
>
> Is there any way to get the automodule directive to use module-level
> docstrings as an introductory text to the module documentation?
>
>
> Thanks,
>
> --
> You received this message because you are subscribed to the Google Groups
> "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sphinx-users?hl=en.
> For more options, visit https://groups.google.com/groups/opt_out.
>
>

[Thomi Richards]

Hi,

On 13 April 2013 17:35, Takayuki Shimizukawa <shimi...@gmail.com> wrote:
> I got the result that you expected with bot Sphinx-1.1.3 and 1.2b1.
> Did you solve your problem yet?

I figured out that my problem was because I didn't realise that
module-level docstrings need to appear *before* any import statements.
So for example, in a module, this works:

"""

"Docstring here"

import os

"""

but this does not:

"""

import os

"Docstring here"

"""

Is this a bug in sphinx, or is this a python requirement that I never
realised before?


Cheers,



--
Thomi Richards

[Takayuki Shimizukawa]

Hi Thomi,

2013/4/14 Thomi Richards <tho...@gmail.com>:

> On 13 April 2013 17:35, Takayuki Shimizukawa <shimi...@gmail.com> wrote:
>> I got the result that you expected with bot Sphinx-1.1.3 and 1.2b1.
>> Did you solve your problem yet?
>
> I figured out that my problem was because I didn't realise that
> module-level docstrings need to appear *before* any import statements.
> So for example, in a module, this works:

-snip-

> Is this a bug in sphinx, or is this a python requirement that I never
> realised before?

It is a python's specification.

A string literal which appears as the first expression in a class,
function or module.
http://docs.python.org/2.7/glossary.html#term-docstring

If you want to place docstring after some statements (import or else),
you can be set
__doc__ variable it.

import os
__doc__ = "Docstring here"

[Zbigniew Jędrzejewski-Szmek]

On Sun, Apr 14, 2013 at 08:28:47AM +1200, Thomi Richards wrote:
> On 13 April 2013 17:35, Takayuki Shimizukawa <shimi...@gmail.com> wrote:
> > I got the result that you expected with bot Sphinx-1.1.3 and 1.2b1.
> > Did you solve your problem yet?
>
> I figured out that my problem was because I didn't realise that
> module-level docstrings need to appear *before* any import statements.

> Is this a bug in sphinx, or is this a python requirement that I never
> realised before?

A python requirement.

Zbyszek

[Mark Eichin]

You can demonstrate this by running pydoc on the module; if your docstring isn't the first thing, pydoc won't see it either (nor will a "print __doc__" in the file.) pylint will also report

foo.py:1: [C] Missing docstring
foo.py:3: [W] String statement has no effect

for a misplaced docstring (it's not clever enough to notice that the two are related, though.)

--
You received this message because you are subscribed to the Google Groups "sphinx-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
To post to this group, send email to sphinx...@googlegroups.com.
Visit this group at http://groups.google.com/group/sphinx-users?hl=en.
For more options, visit https://groups.google.com/groups/opt_out.

--
_Mark_ <eic...@thok.org> <eic...@gmail.com>

[Thomi Richards]

Hi,

On 15/04/2013 4:12 AM, "Mark Eichin" <eic...@gmail.com> wrote:

>
> foo.py:1: [C] Missing docstring
> foo.py:3: [W] String statement has no effect
>
> for a misplaced docstring (it's not clever enough to notice that the two are related, though.)
>

Cool, thanks for the tip. I'm not sure how I missed that.

Thanks!

[chris....@noaa.gov]

Hmm,

I've got my module docstring as the first thing in teh file -- after the #! line...

and it still doesn't show up in the docs.

the module:

#!/usr/bin/env python

"""

outputters.py

module to define classes for GNOME output:

  - base class

  - saving to netcdf

  - saving to other formats ?

"""

import os

import copy

and in my rst:

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

.. automodule:: gnome.outputters   

.. autoclass:: Outputter

    :members:

    :show-inheritance:

But the docs jump right to the Outputter class  -- no docstring for the module

and this is the case all over my project.