[jira] [Comment Edited] (BEAM-693) pydoc is not working

["Marco Buccini (JIRA)" <ji...@apache.org>]

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

Marco Buccini edited comment on BEAM-693 at 10/25/16 7:46 PM:
--------------------------------------------------------------

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.

PS: If we want to document pydoc in the README, a few lines could be spent to mention that python setup.py develop is required (unless the package is installed with pip/another method; but it has to be there)


was (Author: makronized):
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)