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.
Related
Python has a built-in function called help() which returns the docstrings on methods or functions, per the turtle documentation. For example, say I was to type this:
>>> help('os')
I get greeted with
Help on module os:
NAME
os - OS routines for NT or Posix depending on what system we're on.
MODULE REFERENCE
https://docs.python.org/3.8/library/os
The following documentation is automatically generated from the Python
source files. It may be incomplete, incorrect or include features that
are considered implementation detail and may vary between Python
implementations. When in doubt, consult the module reference at the
location listed above.
. . .
and so forth. It is quite simple to find the module reference by just looking at this, but say I was collecting the references to 100 different modules. It would take quite some time and would be very repetitive work.
How can I parse through each help() function for the link to the module's documentation? It would involve finding a similar value such as https:// or .org or .com.
I'd argue that you actually don't need to do any parsing, since as far as I know, all the standard library Python modules have documentation accessible at the URL https://docs.python.org/<version>/library/<modulename>. It would be far more efficient to construct the URL according to that pattern compared to parsing the help text.
That being said, if you really do want to parse the help text, the re.search function should be useful. You can write a regular expression to match the URL of a Python standard library documentation page and presumably the first match should be the result you want.
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 have I small module that I use inside one of my projects. Now I decided to place it on github so now I am writing some docstrings and cleaning the code.
I have a composition of 2 classes so the initialization looks like this:
foo = Class_1()
bar = Class_2(param1=foo)
I know that the first argument to the Class_2 has to be an instance of Class_1 or the code won't work. But it may be clear only for me as I wrote code of Class_2, but when using module as API it may be unclear for a user that param1 has to be an instance of Class_1. If someone will use bar = Class_2(param1='foo'). The trackback will be bad and it will be impossible to understand what happened. So the question is: do I need to check in my __init__ that isinstance(param1, Class_1) and if no raise an excaption with an appropriate message, or writing good documentation is enough?
This is very opinion-based (not great for StackOverflow in particular) - but in my opinion, you should do both.
On the one hand, using isinstance() and exception-handling are both good defensive-coding practices.
On the other hand, inline documentation is nice. Per the Python developer guide:
The markup used for the Python documentation is reStructuredText, developed by the docutils project, amended by custom directives and using a toolset named Sphinx to post-process the HTML output.
Some IDEs, such as JetBrains PyCharm, are configured to automatically pick up well-formed reST docstrings and perform automated type-checking based on those conventions (which I've found to be really useful). See also: PEP 257 and What is the standard Python docstring format? for details.
I want to automatically add sphinx comment under head functions and classes.
When I press Enter after head function or class, comment could be implemented like this:
def func(a): #<Enter>
"""
Args:
a (type): The name to use.
Returns:
type. The return
"""
Is it possible to configure .vimrc (.vimrc.local)? Do you know command for this? Or may be plugin?
Though you can do this with the built-in (insert-mode) mappings, you'll soon want to do more advanced insertions.
snippets are like the built-in :abbreviate on steroids, usually with parameter insertions, mirroring, and multiple stops inside them. One of the first, very famous (and still widely used) Vim plugins is snipMate (inspired by the TextMate editor); unfortunately, it's not maintained any more; though there is a fork. A modern alternative (that requires Python though) is UltiSnips. There are more, see this list on the Vim Tips Wiki.
There are two things to evaluate: First, the features of the snippet engine itself, and second, the quality and breadth of snippets provided by the author or others.
I have many python files.
Each file has functions. That's it. I don't do anything with classes.
Will Sphinx (or another documentation software) still create the documentation for it, and if so, what will it look like?
Yes, of course. That's one of the many normal ways to program in Python. You don't have to use classes -- in fact, many of the modules that come with Python are just collections of functions. Any Python documentation tool will be prepared to deal with this.
Ideally, Python functions and classes are all documented in a specific way that the language (and documentation-generating software) can see, called a docstring. If you put a string immediately after every function definition, like this:
def double(number):
"""Returns number times 2. May behave poorly if number isn't actually a number"""
return number * 2;
...then you can get the function double's docstring from double.__doc__.
For a more detailed description of how to write good docstrings, see PEP8. Search for "Documentation Strings" to skip to the part you care about.