beam-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From "Marco Buccini (JIRA)" <j...@apache.org>
Subject [jira] [Commented] (BEAM-693) pydoc is not working
Date Tue, 25 Oct 2016 19:44:58 GMT

    [ https://issues.apache.org/jira/browse/BEAM-693?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=15606272#comment-15606272
] 

Marco Buccini commented on BEAM-693:
------------------------------------

Hello Ahmet,

I have spent some time investigating this issue. I think pydoc is supposed to be used exactly
as you did, in case you want to have it in a browser. I mean, if you run it from a directory,
it will show you all the packages installed in Python + the .py modules available in that
directory. Basically, it tries to import your Python modules + the path you are in and recursively
all the (sub) members of the modules present in that directory.

To quote the docs (https://docs.python.org/2/library/pydoc.html):

> For modules, classes, functions and methods, the displayed documentation is derived from
the docstring (i.e. the __doc__ attribute) of the object, and recursively of its documentable
members. 

and

> When pydoc generates documentation, it uses the current environment and path to locate
modules. Thus, invoking pydoc spam documents precisely the version of the module you would
get if you started the Python interpreter and typed import spam.


To answer your question, pydoc is a tiny module, so I am not sure if there is really a standard
for it. Some projects provide a Jenkins job to generate the docs and serve them - after all,
they are just HTML files (e.g., pydoc -w `find apache_beam -name '*.py'`).
However, I see this less and less happening; now, the de-facto standard is read-the-docs,
but that requires reStructuredText/Markdown documentation, meaning manual documentation, which
needs to be kept up-to-date, etc.



> pydoc is not working
> --------------------
>
>                 Key: BEAM-693
>                 URL: https://issues.apache.org/jira/browse/BEAM-693
>             Project: Beam
>          Issue Type: Bug
>          Components: sdk-py
>            Reporter: Ahmet Altay
>            Priority: Minor
>
> Repro:
> Start the pydoc server (pydoc -p 8888) and navigate to the apache_beam root:
> http://localhost:8888/apache_beam.html
> Following errors are shown instead of the actual documentation:
> problem in apache_beam - <type 'exceptions.ImportError'>: No module named avro
> problem in apache_beam - <type 'exceptions.ImportError'>: cannot import name coders



--
This message was sent by Atlassian JIRA
(v6.3.4#6332)

Mime
View raw message