Mailing-List: contact commits-help@beam.incubator.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@beam.incubator.apache.org
Date: Tue, 25 Oct 2016 19:44:58 +0000 (UTC)
From: "Marco Buccini (JIRA)" <jira@apache.org>
To: commits@beam.incubator.apache.org
Message-ID: <JIRA.13008392.1475106245000.82558.1477424698418@Atlassian.JIRA>
In-Reply-To: <JIRA.13008392.1475106245000@Atlassian.JIRA>
References: <JIRA.13008392.1475106245000@Atlassian.JIRA> <JIRA.13008392.1475106245744@arcas>
Subject: [jira] [Commented] (BEAM-693) pydoc is not working
MIME-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 7bit
archived-at: Tue, 25 Oct 2016 20:47:33 -0000


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