8000 Added docstring popular formats by sam4u3 · Pull Request #14 · Akuli/python-tutorial · GitHub
[go: up one dir, main page]

Skip to content

Added docstring popular formats #14

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Jul 25, 2020
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
126 changes: 126 additions & 0 deletions basics/docstrings.md
Original file line number Diff line number Diff line change
Expand Up @@ -121,6 +121,132 @@ It's recommended to always use `"""strings like this"""` for docstrings,
even if the docstring is only one line long. This way it's easy to add
more stuff to it later.

## Popular Docstrings Format

There might be different documentation strings available. You need not need to worry about the fact that you have to reinvent the wheel to study all. The formats of all the Documentation strings are nearly similar. The patterns are similar, but there are only nitty-gritty changes in each format.

##### 1) Sphinx Style :

Sphinx is the easy and traditional style, verbose and was initially created specifically for the Python Documentation. Sphinx uses a reStructuredText which is similar in usage to Markdown.

```python
class Vehicle(object):
'''
The Vehicle object contains lots of vehicles
:param arg: The arg is used for ...
:type arg: str
:param `*args`: The variable arguments are used for ...
:param `**kwargs`: The keyword arguments are used for ...
:ivar arg: This is where we store arg
:vartype arg: str
'''


def __init__(self, arg, *args, **kwargs):
self.arg = arg

def cars(self, distance, destination):
'''We can't travel a certain distance in vehicles without fuels, so here's the fuels

:param distance: The amount of distance traveled
:type amount: int
:param bool destinationReached: Should the fuels be refilled to cover required distance?
:raises: :class:`RuntimeError`: Out of fuel

:returns: A Car mileage
:rtype: Cars
'''
pass

```

##### 2) Google Style :
Google Style is easier and more intuitive to use. It can be used for the shorter form of documentation. A configuration of python file needs to be done to get started, so you need to add either sphinx.ext.napoleon or sphinxcontrib.napoleon to the extensions list in conf.py.

```python
class Vehicles(object):
'''
The Vehicle object contains a lot of vehicles

Args:
arg (str): The arg is used for...
*args: The variable arguments are used for...
**kwargs: The keyword arguments are used for...

Attributes:
arg (str): This is where we store arg,
'''

def __init__(self, arg, *args, **kwargs):
self.arg = arg

def cars(self, distance,destination):
'''We can't travel distance in vehicles without fuels, so here is the fuels

Args:
distance (int): The amount of distance traveled
destination (bool): Should the fuels refilled to cover the distance?

Raises:
RuntimeError: Out of fuel

Returns:
cars: A car mileage
'''
pass

```

##### 3) Numpy Style :

Numpy style has a lot of details in the documentation. It is more verbose than other documentation, but it is an excellent choice if you want to do detailed documentation, i.e., extensive documentation of all the functions and parameters.

```python
class Vehicles(object):
'''
The Vehicles object contains lots of vehicles

Parameters
----------
arg : str
The arg is used for ...
*args
The variable arguments are used for ...
**kwargs
The keyword arguments are used for ...

Attributes
----------
arg : str
This is where we store arg,
'''

def __init__(self, arg, *args, **kwargs):
self.arg = arg

def cars(self, distance, destination):
'''We can't travel distance in vehicles without fuels, so here is the fuels

Parameters
----------
distance : int
The amount of distance traveled
destination : bool
Should the fuels refilled to cover the distance?

Raises
------
RuntimeError
Out of fuel

Returns
-------
cars
A car mileage
'''
pass
```

## Documenting other stuff

Docstrings aren't actually limited to functions. You can use them for
Expand Down
0