Vipul Gupta
Vipul is a software engineer at balena and a documentarian running his docs initiative called Mixster. He advocates strongly for open-source, cheesecakes and party parrots.
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
-
DocumentComment 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
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
- 5 simple things you can do to improve OSS docs - Erin McKean
- Write the Docs Community Resouces & Slack
- Google's Technical Writing Course
- Eight Rules to good docs! - Orielly
- Friction Logging
- Real Python's blog on starting with Python docs
- Icons from Flaticon attributing Pixel Perfect, Gandy Dave
- And, so many more.
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.
[PyDelhi] Documenting your Python project: Right the Docs
By Vipul Gupta
