How to read Python's Documentation: BEHIND THE SCENES!

By

Welcome!

Hi! Welcome to this section where we will dive into a “tool” that you will use and learn to love throughout your Computer Science journey and/or career.
  • Let’s say you’ve found the Build-in Python function round() and you would to know more about how it works. What do you do? You go to PYTHON'S DOCUMENTATION!

Concept:

First of all, let’s start by describing what is Documentation:


Importance and First Impressions

  • As you can see, it is extremely important since it tells you how a software (or in this case, a programming language) can be used.
  • At first it may seem daunting and you will find a lot of technical terminology you maybe haven’t heard of next to the information you actually need, but don’t worry, through experience you will learn to determine what is relevant to your needs and what isn’t.
  • Trust me, I’ve been through this and at first I felt like documentation was very intimidating but with practice I learned to love it because it is through documentation that programming becomes an incredibly powerful tool. Without documentation you wouldn’t know how to use a specific function or what the programming language you’re using is capable of.

Let's get started!

Reading through it and getting used to its basic structure is really important, so… Let’s start!
Since we’re working with Python, we will look into how to find a specific function on its documentation but this applies to finding any feature of the programming language you may need.
First of all, one way of accessing Python’s documentation is by Googling “Python Documentation” and clicking on the first result as shown below.

Welcome!

Great! Welcome to the world of documentation! Let’s dive into the specific details you will find on the main page:
  • Python’s version will be displayed.
WARNING: The documentation may change from one version to the next, so be careful to use the right version on the website. At the end of this tutorial you can find how to change documentation versions once you’re inside the website.
  • You will also find a search bar where you can type what you need to look for.


The round() function

  • Let’s say we need to look for the round() function because we want to learn more about it and how to use it.
We search for it and click on the result that says Built-in Functions (functions that come predefined in Python)

Function documentation

When we click on it, we are immediately taken to the function’s documentation.
This amount of information may seem overwhelming but we’ll break down its basic structure and you will be able to find the information you need. So… Let’s dive in!


Basic Structure

The function’s documentation has this basic structure:
  • The function’s name and parameters in parentheses
  • The function’s main description on the first paragraph or sentence.
  • Additional details you may need to know when using the function.
  • Warnings and important comments on the function’s behavior and use cases.
Usually, to get a general idea of how the function works, you can read the function’s main description.



Parameters in Square Brackets?

I’m sure you’re curious on why some parameters are enclosed in square brackets and why some aren’t.
  • The parameters that are not enclosed in square brackets are required, they must be provided to the function for it to run properly.
  • The parameters that are enclosed in square brackets are optional. You can either pass a value for them when you call the function or only pass the required parameters and the function will still run.
       If you don’t pass a value for an optional parameter, this parameter will take a default value that will be described in the documentation.

Going back to the documentation

Let’s see how we can determine the default value for round()’s second parameter, ndigits.

Findings

Going back to the documentation, we see that on the function’s main description we find a sentence that says that if the parameter ndigits is omitted, the function will return the nearest integer to its input. We can also find additional information on this one-parameter scenario on the second paragraph.


Congratulations!

Congratulations! You’ve read your first function documentation! You should be really proud of yourself. This is just the beginning of a life-long friendship between you and documentation.

TIPS:

When discussing code with others or asking questions on the forums, it’s often very useful to share a link to the documentation of a function we’re having problems with or that we have questions about.
If we place the cursor over the function’s name or parameters, an icon will be displayed to the right. If we click on this icon, we can copy the URL on the browser's search bar and share a link to the function’s documentation. We can then paste this link where we want to share it and the person clicking on the link will get to the same place in Python’s documentation without having to scroll down or search any further.

WARNING: VERY COMMON PROBLEM

  • Remember we talked about Python’s version changing the documentation?
Let’s say we Google “Python round” to find more information on the round() function.
We usually tend to click on the first result. But this may lead us to a wrong version of Python’s documentation. But Don’t Worry! We can change the version we want to read as shown on the diagram below.



I hope this helps!
If you have any questions please do not hesitate to ask : ) Community TAs and your classmates will be on the forums to help you.
Estefania.

Comments

Post a Comment