[
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)
