New to programming and python altogether. In the book I'm learning from, the author suggested I find out the purpose of Pydoc.
I did a google search on it, and found a match (from Gnome Terminal) but it didn't make much sense to me. Anyone mind simplifying a bit?
Pydoc is a help / documentation module for Python.
Use this on your Windows terminal to understand what a function in python does :
python -m pydoc <function>
eg.
python -m pydoc raw_input
If the documentation for a particular function is very long, use 'q' to get out of it.
e.g. in case of
python -m pydoc Tkinter
Pydoc module in Python can be used to generate documentation in the form of html pages or even on the console
python -m pydoc
This command gives options like view the pydoc for a file, -k search for different libraries, -p allows to open a page in web browser to view python packages, -g provides a graphical interface for looking documentation, -w writes an html output. Below are the sample commands that you can fire for testing.
python -m pydoc yourpythonfile
python -m pydoc -k ftplib
python -m pydoc -p 314
python -m pydoc -w file
I have created two sample files in a directory file1.py and file2.py which has a simple code with a single line of comment.
def f2m(ft):
""" Return the number of meters eq to feet """
return 0.30 * ft
One way to see the comment of the files is to simply write below in the same file and you can run python file.py and it would show the comments.
help(f2m)
Other way to see this is to write the command
python -m pydoc file1
One more way to see the comments in an html page by typing this command and exporting it to html
python -m pydoc -w <dir>
If you have multiple python files and if you want to generate HTML into separate folder then simple shell commands can do the job. Below code generates a folder 'htmldocs' and then generates html and moves them to this new folder. If you open any one at the right hand top corner you can see index option through which you can navigate through other pages.
mkdir -p htmldocs
pydoc -w `find . -name '*.py'`
mv *.html htmldocs
It's a tool to generate python-style documentation see http://docs.python.org/2/library/pydoc.html
You may want to take a look at Sphinx too.
Pydoc is the documentation generation system for Python. Say you can document your functions using the Pydoc standard and then it can be used to generate documentation in your code.
The pydoc module automatically generates documentation from Python modules. The documentation can be presented as pages of text on the console, served to a Web browser, or saved to HTML files.
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. If there is no docstring, pydoc tries to obtain a description from the block of comment lines just above the definition of the class, function or method in the source file, or at the top of the module.
For more info on respective Python versions - Python 2.7 - Python 3.5 - Python 3.6
It is the tool that helps to know the word or component of a python program. i.e
>python -m pydoc input
To know what "input" does in code
As a Python learner myself, the easiest way I can describe pydoc is that it is a command used to learn about different commands. The syntax goes as such:
> python -m pydoc 'function'
Example:
> python -m pydoc open
Help on built-in function open in module builtin:
open(...) open(name[, mode[, buffering]]) -> file object
Open a file using the file() type, returns a file object. This is the
preferred way to open a file. See file.__doc__ for further information. <<<
Hope that helps!
pydoc generates online documentation from docstrings...
for example you can see that Numpy.histograms() function's, online documentation is actually made based on that function docstring...
Concise description provided by to Wikipedia: "Pydoc allows Python programmers to access Python's documentation help files, generate text and HTML pages with documentation specifics, and find the appropriate module for a particular job."
Just type pydoc in your terminal where you normaly run python. It will give simple explanation !. : )
