Navigation through Python documentation. Tricks and tips.

Introduction

If programming is the shed, then documentation is the key to it. This is the first comparison that comes to mind when I hear the word documentation. And for sure, if you can understand and navigate documentation, then you don't need guides or tutorials.
The importance of documentation cannot be underestimated, especially for Python developers. Although I will analyze and provide examples of documentation for Python, the tips and tricks in this article are still relevant for any programming language.

What is docstring, and what are the types of documentation in Python?

So, first, let's understand how documentation works in Python. What types of documentation are out there? What is docstring, and why is pydoc such a cool thing?

About __doc__ attribute

As you know, everything in Python is an object, from a string to a module.The so-called docstring is an attribute of __doc__ in every object that Python has.
Type in, and you'll find the __doc__ attribute.

print(dir(str))
		
And now

print("".__doc__)
		
It will return you the description string of class str

str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.
		

Types of documentation for python lanuguage

Now that you and I have updated our knowledge about the __doc__ attribute, let's ask ourselves: What kind of documentation out there for Python programmers even exists?.
There are:
Now let's look at them in order.

Build-in command help

This is the so-called buildin Python function. Quite useful. It works by reading the __doc__ attribute as if it were the object itself, as well as all its methods and attributes.

Documentation generated by pydoc

No doubt, if you are not afraid of the dull interface of the terminal or the not very beautiful design in the browser window, then you will not need any other documentation at all. This is a completely comprehensive tool.
pydoc in terminal pydoc in browser
To open the generated pydoc documentation in your browser, enter:

pydoc -b
		
The pydoc module can also be used as a help function. By typing:

pydoc str
		
You will receive the same documentation when using the help command

str(object='') -> str
str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or
errors is specified, then the object must expose a data buffer
that will be decoded using the given encoding and error handler.
Otherwise, returns the result of object.__str__() (if defined)
or repr(object).
encoding defaults to sys.getdefaultencoding().
errors defaults to 'strict'.
		

Documentation generated by other generators

They work on the same principle as the *pydoc*. The only difference is that they add additional functionality for documentation, and some of them allow you to improve and expand their functionality.
Here are just a few popular ones.
pdoc3
Works with markdown, numpydoc, Napoleon, doctests
Main features:
  • No setup required. Works out of the box.
  • Generates documentation in the form of plain text files, HTML or PDF
  • Built-in web server.
example of pdoc generator 1 example of pdoc generator 2 example of pdoc generator 3
Sphinx
Uses markup language such as reStructuredText by default, and can also work with MyST markup language.
The main features are:
  • Ability to generate documentation in the form of HTML, PDF, ePub, Texinfo, Regular text pages
  • Code highlighting
  • Extended linking
sphinx generator aiogram sphinx generator scrapy sphinx generator requests
MkDoc
Uses markdown as markup language
The main features are:
  • Ability to host your documentation almost anywhere. From github pages to regular websites
  • Easily customizable
  • Lots of cool themes
MkDoc generator openml

Usefull features when using documentation

Useful features for those folks how works a lot in interactive python shell.

Get list of available modules

[Expand] Chevron

help('modules')
			

Get list of keywords

[Expand] Chevron

from keyword import kwlist
print(*kwlist, sep='\n')
			

Get list of build-in functions

[Expand] Chevron

import buildins
print(*buildins.__dict__.keys(), sep='\n')
			

Get objects's attributes and methods

[Expand] Chevron

dir(int)
			

How to navigate through the documentation and use it

Now my favorite part. How exactly am I navigating through the documentation.Especially when you see it for the first time.

Google is your best friend.

For now, it is the best search engine in the world, without a doubt. With Google, anyone can find anything, and it gets even better; he/she/it/me/you can find exactly what we need right now. Just type in a search box for some words. Google search is the best tool for you.
When I'm searching, I'm using the next Google dork.

site:https://example.com intext:"text" keyword1 keyword2

It allows you to quickly find the necessary sections in the documentation.For example. I need to create a keyboard for a Telegram bot. I'm using Aiogram.
Then our search query will be as follows:

site:https://docs.aiogram.dev/en/latest/ intext:"keyboard" build inline
		
We know that we need a keyboard, and we know that one of the types of keyboards is called inline.
intext google search query example using aiogram
We follow the first link and see that in addition to the inline keyboard, there is also a certain builder.replay keyboard. Let's look at it.

site:https://example.com intext:"text" OR intitle:"alt_text"

The OR keyword allows you to list possible search options.Thus, if nothing is found in the text, the search engine will search for page titles.
For example, if we enter

site:https://docs.djangoproject.com/en/5.0/intext:"pants"
		
We will get
empty google query result
But if we supplement our request,

site:https://docs.djangoproject.com/en/5.0/ intext:"pants" OR intitle:"Template"
		
We will get you the pages you are looking for.
example of google query with OR keyword in it

site:https://example.com intext:"text" AND intitle:"alt_text"

The AND keyword allows both variables to be taken into account.
If we take the same query and change OR to AND

site:https://docs.djangoproject.com/en/5.0/ intext:"pants" AND intitle:"Template"
		
Then again, we won't get anything.
empty google query result

Other search operators

Autocompletion and Hints in the IDE

The second most important and necessary thing after Google is code completion and tooltips to select the required function or attribute. It's especially good when autocomplete shows the description and general usage of the selected method or attribute.
This feature is available in any IDE.
vscode autocompletion Nvim autocompletion visula studio autocompletion

Search in the website's documentation

The third most important thing for a programmer is documentation.And since each documentation is different, the approach to each should beindividual. I can only give general recommendations that are suitablefor any documentation.

Conclusion

Do not get me wrong. All the information you need for your projects is always in documentation. But the question is how accessible this information is and how to pull it out of the documentation.
Not a single document generator has such great search and look-up abilities as Google Search.
Anyway, why are we even looking for information? We have a problem, and a problem is the first source of question. And we all know already who is the best in a field to answer such questions. Right search engines in general and Google in particular.
Any documentation has an index, cross-linking, table of contents, keywords, etc. I will say that's great, and everything from the list above is needed. But search engines, by nature, are better at looking for information than documentation.
Of course, ChatGPT is a powerful thing. But he has one, for me, fatal flaw. He will give one single answer, no sources given, no alternatives. And ChatGPT works on top of Google and its huge database of sites.Therefore, here is my word. Google must have.

heart 0
3 connected dots 0

Comments

(0)
Avatar by default
None
Leave a comment
Leave a comment
βœ”