I was wondering if it is possible to use POD(plain old documentation) with Python? And how should I do it?
There does not appear to be a directly supported way to use POD inline in a Python file. However, Python modules (including the Python standard library) are documented using reStructuredText. This is usually done using Sphinx, which produces documentation from reStructuredText-formatted docstrings. Sphinx and rst were specifically designed to fill a similar niche to POD.
Yes. Use '''.
#!/usr/bin/python3
'''
=pod
=head1 NAME
...
=cut
'''
import sys
Related
Sphinx allows linking to external documentation (such as the standard library docs) via intersphinx.
Is it possible to link to the definition of special methods like __del__(), without just making a regular link?
Ok, so in my case, I just needed to link to the object.__del__ method:
:py:meth:`__del__() <object.__del__>`
To do this generically:
Use python -m sphinx.ext.intersphinx https://docs.python.org/3/objects.inv to get the inventory of the python docs. You're gonna want to pipe the output through less or grep or save it to a file
Search through the results for the thing you're looking for. For special methods, it'll probably be object.__spam__
Look at the section the thing is under, and add it to your rst
I've noticed in a lot of examples there are "import ..." as such in Haskell;
-- file: ch05/PrettyJSON.hs
module PrettyJSON
(
renderJValue
) where
import Numeric (showHex)
import Data.Char (ord)
import Data.Bits (shiftR, (.&.))
import SimpleJSON (JValue(..))
import Prettify (Doc, (<>), char, double, fsep, hcat, punctuate, text,
compact, pretty
Do you have to create those import packages or are they already included in the programming language (or computer).
If you don't need to create an import, then where do you get it and can you view the coding?
A Haskell-centric answer:
import Numeric (showHex)
This line imports the showHex function within the Numeric module. Modules are groups of functions, data types and other such things, arranged in a way to allow easy reuse. Some modules come with the basic installation of the compiler, others you can install later on (in Haskell, they are distributed as packages, which you can install with tools such as cabal-install), and finally there are those you define for use in your programs. In fact, the snippet you included in your question is the beginning of a module, called PrettyJSON, which makes the renderJValue function available when you import it elsewhere.
and can you view the coding?
Most Haskell packages written by other people that you can install are distributed through Hackage. By browsing Hackage, you can find documentation for the packages and their modules, as well as read their source code. For instance, here is the definition of showHex in the Numeric module. (By the way, Numeric is part of the base package. base comes with the compiler, and so you don't need to install anything else to use it.)
If you are talking about Python, all the packages are already pre-included.
For example:
import statistics
or:
from statistics import variance
and then you can use the function within that package, do check out the Python Docs for more information on the various packages. This is just a short example:
statistics.variance(a)
Importing packages allows you to leverage the power of these languages in a convenient way. Some packages are modules that come built-in with the language of your choice and some are built by programmers to create added functionality. From the Python docs:
Python provides standardized solutions for many problems that occur in everyday programming.
Check out this simple example in Python in which you create a `fibo.py file and then import it in your terminal like so:
import fibo
print fibo.fib(1000)
And perform Fibbonacci evaluations on a range of numbers. I suggest you read over the docs regarding Modules and more examples on how to use them, that might help clarify some of your questions.
Is there an equivalent module for Groovy as Python's os.path?
Most of the os.path functionality is found in the methods on the java.io.File class. In addition, if you're using Java 1.7, there are some additional methods in java.nio.file.Files.
Also note that groovy transparently adds some new addtional functionality on top of Java. These additional methods are documented here: http://groovy.codehaus.org/groovy-jdk/java/io/File.html
The standard java.io.File Java class can do a lot of the same things, and Groovy adds its own extensions (see http://groovy.codehaus.org/groovy-jdk).
In the standard Python documentation, system calls appear as bold, fixed-width font. You can see this in the asyncore section, when it mentions select() or poll() for example:
http://docs.python.org/py3k/library/asyncore.html
I checked the source code for asyncore, and it has no special markups for these functions, so I'm not sure how one convinces Sphinx to do this. Is there a simple directive I can add to index.rst to make this work like I want?
Where did you see that there is no special markup for the C function calls? When I looked at the latest source for this file it has :cfunc:'select', which I think is old style Sphinx markup for C code. For the latest way of doing it read up on The C Domain.
I couldn't find a documentation about this function...
I specifically want to know what the parameters are and what do the parameters exactly represent...
using python 3
The convention in Python is to use a single leading _ for non-public methods and instance variables. So, _siftdown is not intended to be called externally and, thus, is not documented in the standard library documentation. If you want to examine how it works, look at the code. Note that the latest Python 3.2 documentation now includes links to the source code; see the link near the top of the page here.