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:
- Built-in Python interpreter command help.
- Generated by pydoc (both in terminal and browser)
- Generated by other pydoc-like modules and tools.
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.
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.
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
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
Usefull features when using documentation
Useful features for those folks how works a lot in interactive python shell.
Get list of available modules
[Expand]
Get list of keywords
[Expand]
Get list of build-in functions
[Expand]
Get objects's attributes and methods
[Expand]
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.
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
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.
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.
Other search operators
- “search term” For an exact match with the search phrase.
- OR Will return results for either one or two search phrases.
- AND Will return results for only two search phrases.
- - Removes the search phrase from the search
- * Wildcard. Will match any word or phrase.
- ( ) Groups multiple search phrases or operators to control how the search displays results.
- $ Price search.
- define: Displays the meaning of a word.
- Cache: Returns the most recent version of the web page.
- filetype: Shows only pages of a certain type (PDF, DOCX, TXT, PPT, ...)
- site: Limits the search to one site.
- related: Finds similar sites.
- intitle: Finds pages with certain words in the title.
- allintitle: Finds pages that have all the words in the title.
- inurl: Finds pages whose URL includes a particular phrase or word.
- allinurl: Finds pages whose URL includes a particular phrase or word in its entirety.
- intext: Finds pages whose body text contains certain words.
- allintext: Finds pages whose body text contains all the specified words.
- AROUND(X) Returns only those pages with exactly X number of occurrences of words or phrases.
- weather: Searches for weather in a specific location.
- stocks: Returns information about stocks.
- map: View results on a map to search for a location.
- movie: Search for movies.
- in Converts one value to another. Currency, units of measurement
- source: Search Google News.
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.
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.
- Search for a table of contents or index. It will help you find out the structure of the project and its scale.
- If you find the page you need, use the CTRL+F key combination. This makes it faster and easier to find the information you need.
- There is always something interesting in the footer.
- Take it a step higher. Perhaps the documentation also has guides, how-tos, or tutorials; do not ignore them. It will help you to get started.
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.
0
Used termins
- Function ⟶ A reusable block of code that performs a specific task. Functions take inputs, called parameters or arguments, process them, and can return a value. They help organize code, making it more modular, readable, and maintainable.
Related questions
- How do I use image and file fields? Using a FileField or an ImageField in a model takes a few steps: 1) In your settings file, you’ll need to define MEDIA_ROOT 2) Add the FileField or ImageField to your model 3) All that will be stored in your database is a path to the file (relative to MEDIA_ROOT)