Python Zero to Heros

Online Absolute Beginner Python Tutorials 

Every Sunday 2pm (UK time/ BST)

Get this slide deck:

slides.com/cheukting_ho/python-docs

Recap

Beginner topics:

Python objects - int, float, str, list, dict, bool

Control flows - if-else, for loop, while loop

Functions, modeuls, classes and decorators

strings operations and regex with re

Testing:

pytest with fixtures and mock

property-based testing

python linters & auto-formatters

TDD

Intermedite topics:

Iterators, generators, async

Why documentation is important?

• For users (including you) to understand the code
   
• As a quick reference
   
• Avoid mistakes

In Python

Use # as comments, which acts as notes

 

But that's not good enough

 

Docstrings is embedded in the Python object and can be called as reference

Style in Docstrings

 

- Google style

 

- Numpy style

 

https://realpython.com/documenting-python-code/#docstring-formats

Let's try it

Sphinx

Sphinx

 

Sphinx is a documentation generator written and used by the Python community. It is written in Python, and also used in other environments. 

- Wikipedia

 

The good thing about using Sphinx - it turns your docstrings into a website!

 

https://www.sphinx-doc.org/en/master/usage/quickstart.html

Documentation site generation flow

Nothing better than a real example