Documenting your next Python Project:

Right the Docs

@vipulgupta2048

@vipulgupta2048

Who is dis Vipul?

  • Builds stuff at balena full-time
  • Runs a blog & OSS documentation initiative by the name, Mixster 
  • Runs content for PyCon India 2020
  • Organises meetups with the team of PyDelhi!
  • Recent pseudo-graduate no thanks to Covid
  • Loves Party Parrots way too much

@vipulgupta2048

Name any major open-source project

without documentation

@vipulgupta2048

What will we cover here?

We will be taking a project by project tour on

  • What to exactly document in your project?
  • Select the right tools, as your project grows
  • Taking inspiration and making right decisions

@vipulgupta2048

Right
The
Docs

@vipulgupta2048

The newborn

  • Project is couple of Python scripts old
  • You are possibly the only user (until it becomes famous)
  • Initial commit on your side-projects
  • Every project goes through this stage

@vipulgupta2048

  • Automation logic/use-cases
  • Scraping scripts, bots, random word generators
  • Simple web apps
  • In some cases, internal documentation as well.

Examples

@vipulgupta2048

Documenting the project

  • Document Comment your code
  • Have a README in place 
    • Getting Started/Installation
    • Configuration
    • Deployment 
    • Contributing & License

@vipulgupta2048

```
Commenting Code via Type Hinting (Python 3.5+)
Type hinting was added to Python 3.5 and is an additional form
to help the readers of your code. Here’s a quick example:
````
def hello_name(name: str) -> str:
    return(f"Hello {name}")
class SimpleClass:
    """Class docstrings go here."""

    def say_hello(self, name: str):
        """Class method docstrings go here."""

        print(f'Hello {name}')

Examples taken from Real Python's Python Documentation blog

@vipulgupta2048


def get_spreadsheet_cols(file_loc, print_cols=False):
    """Gets and prints the spreadsheet's header columns

    Parameters
    ----------
    file_loc : str
        The file location of the spreadsheet
    print_cols : bool, optional
        A flag used to print the columns to the console (default is
        False)

    Returns
    -------
    list
        a list of strings used that are the header columns
    """

    file_data = pd.read_excel(file_loc)
    col_headers = list(file_data.columns.values)

    if print_cols:
        print("\n".join(col_headers))

    return col_headers

@vipulgupta2048

The teenager

  • Tons of Modules,
  • Abstractions with classes
  • TDD with both unit and integration tests
  • Possibly with CI/CD integration
  • Documentation probably is open-source

@vipulgupta2048

Examples!

  • SDK docs
  • API docs
  • CLI documentation

@vipulgupta2048

@vipulgupta2048

@vipulgupta2048

Popular Documentation Generators

  • Pdoc for simpler, API docs
  • Swagger for OpenAPI Specifications docs
  • PyCoo, very interesting side-by-side docs narrative
  • Sphinx (Community champion)
  • doc2md for generating documentation from docstring
  • handsdown, an alternative to docstrings docs generator

@vipulgupta2048

Growing up

  • Code is now used by thousands of people
  • Both code and docs are now open-source
  • Maintained by the community
  • Plugins and extensions starts building 
  • Well-defined release workflow and possibly semantic versioning

@vipulgupta2048

Reference #1: Documentation Driven Development: Success behind Django

Reference #2: Daniele Procida's How documentation works, and how to make it work for your project

4 major parts all documentation should have

  • Tutorials
  • How-To Guides
  • References
  • Discussions

@vipulgupta2048

Examples

  • A library or package
  • A framework 
  • Utilities like
    • Testing tools
    • Automation tools
    • And so much more

@vipulgupta2048

@vipulgupta2048

Django Project's Overview Page

@vipulgupta2048

Maintenance & Scaling

Growing healthy documentation

  • Sectioning off the docs 
  • Giving real examples
  • Cookbooks
  • Streamline information flow
  • Product screenshots

@vipulgupta2048

  • Step by step Tutorials
  • Blogs
  • Videos
  • References
  • Scaling the design

@vipulgupta2048

How do I start?

  • No Documentation
  • Some Documentation
  • Complete Documentation
  • Good Documentation
  • Great Documentation

@vipulgupta2048

References & links

When you realize you have the power to write great docs!

And, that's about it!

Questions? Get in touch.

Mixster offers first consultation free on your docs, if things work out first round of ice-creams are on us!

Vipul Gupta

Part-time remote setup builder, writes half-decent blogs and makes memes that no one asked for.

Made with Slides.com