Episode 118
Creating Documentation With MkDocs & When to Use a Python dict
The Real Python Podcast · Real Python
July 22, 202254m 45s
Audio is streamed directly from the publisher (dts.podtrac.com) as published in their RSS feed. Play Podcasts does not host this file. Rights-holders can request removal through the copyright & takedown page.
Show Notes
<p>How do you start building your project documentation? What if you had a tool that could do the heavy lifting and automatically write large portions directly from your code? This week on the show, Christopher Trudeau is here, bringing another batch of PyCoder’s Weekly articles and projects.</p>
<p>We talk about a Real Python step-by-step project from Martin Breuss about MkDocs. The project walks you through generating nice-looking and modern documentation from Markdown files and your existing code’s docstrings. The final step is to deploy your freshly generated documentation to a GitHub repository.</p>
<p>Christopher talks about a pair of articles arguing for and against using Python dictionaries. The first article, “Just Use Dictionaries,” pushes to keep things simple, while the second article, “Don’t Let Dicts Spoil Your Code,” contends that complex projects require something more specific.</p>
<p>We cover several other articles and projects from the Python community, including discussing the recent beta release of Python 3.11, 2FA for PyPI, procedural music composition with arvo, building a tic-tac-toe game with Python and Tkinter, common issues encountered while coding in Python, a type-safe library to generate SVG files, and a lightweight static analysis tool for your projects.</p>
<div class="alert alert-primary" role="alert">
<p><strong>Course Spotlight:</strong> <a href="https://realpython.com/courses/dicts-arrays-ideal-data-structure/">Dictionaries and Arrays: Selecting the Ideal Data Structure</a> </p>
<p>In this course, you’ll learn about two of Python’s data structures: dictionaries and arrays. You’ll look at multiple types and classes for both of these and learn which implementations are best for your specific use cases.</p>
</div>
<p>Topics:</p>
<ul>
<li>00:00:00 – Introduction</li>
<li>00:02:39 – Python 3.11 Release May Be Delayed</li>
<li>00:03:39 – The cursed release of Python 3.11.0b4 is now available</li>
<li>00:05:01 – PyPI 2FA Security Key Giveaway</li>
<li>00:08:01 – Build Your Python Project Documentation With MkDocs</li>
<li>00:14:12 – Don’t Let Dicts Spoil Your Code</li>
<li>00:16:22 – Just Use Dictionaries</li>
<li>00:20:12 – Sponsor: Snyk.io </li>
<li>00:20:51 – Procedural Music Composition With arvo</li>
<li>00:29:10 – Build a Tic-Tac-Toe Game With Python and Tkinter</li>
<li>00:33:59 – Video Course Spotlight</li>
<li>00:35:35 – Most Common Issue You Have Coding With Python?</li>
<li>00:45:00 – svg.py: Type-Safe Library to Generate SVG Files</li>
<li>00:48:27 – semgrep: Lightweight Static Analysis for Many Languages</li>
<li>00:53:46 – Thanks and goodbye</li>
</ul>
<p>News:</p>
<ul>
<li><a href="https://mail.python.org/archives/list/[email protected]/thread/3JWVCSBPBFWY5ZWSJ7RYB6FS5NIMCEOY/">Python 3.11 Release May Be Delayed</a></li>
<li><a href="https://discuss.python.org/t/the-cursed-release-of-python-3-11-0b4-is-now-available/17274">The cursed release of Python 3.11.0b4 is now available - Python.org</a>. </li>
<li><a href="https://twitter.com/pypi/status/1545455297388584960">“We’ve begun rolling out a 2FA requirement”: PyPI on Twitter</a></li>
<li><a href="https://pypi.org/security-key-giveaway/">PyPI 2FA Security Key Giveaway</a></li>
</ul>
<p>Topic Links:</p>
<ul>
<li><a href="https://realpython.com/python-project-documentation-with-mkdocs/">Build Your Python Project Documentation With MkDocs</a> – In this tutorial, you’ll learn how to build professional documentation for a Python package using MkDocs and mkdocstrings. These tools allow you to generate nice-looking and modern documentation from Markdown files and, more importantly, from your code’s docstrings.</li>
<li><a href="https://roman.pt/posts/dont-let-dicts-spoil-your-code/">Don’t Let Dicts Spoil Your Code</a> – The <code>dict</code> is the go-to data structure for Python programmers, but its loose relationship to the data can be problematic in large data streams. Learn more about why and when you might choose a different data structure.</li>
<li><a href="https://davidvujic.blogspot.com/2022/07/just-use-dictionaries.html">Just Use Dictionaries</a> – Using simple data structures is an important part of keeping it simple, and Python is all about simplicity. Less code means fewer problems. Just use dictionaries. You probably don’t need classes.</li>
<li><a href="https://deepnote.com/@essia/Procedural-music-composition-with-arvo-9b35ebd7-63e0-47bc-a3d5-c503954a083d">Procedural Music Composition With arvo</a> – By using the <code>music21</code> and <code>avro</code> libraries, you can create musical scores programmatically. This article runs you through which libraries you need and how you can compose your own music.</li>
<li><a href="https://realpython.com/tic-tac-toe-python/">Build a Tic-Tac-Toe Game With Python and Tkinter</a> – In this step-by-step project, you’ll learn how to create a tic-tac-toe game using Python and the Tkinter GUI framework. Tkinter is cross-platform and is available in the Python standard library. Creating a game in Python is a great and fun way to learn something new and exciting!</li>
</ul>
<p>Discussion:</p>
<ul>
<li><a href="https://twitter.com/__mharrison__/status/1537164071912497160">Most Common Issue You Have Coding With Python?</a></li>
</ul>
<p>Projects:</p>
<ul>
<li><a href="https://github.com/orsinium-labs/svg.py">svg.py: Type-Safe Library to Generate SVG Files</a></li>
<li><a href="https://github.com/returntocorp/semgrep">semgrep: Lightweight Static Analysis for Many Languages</a></li>
</ul>
<p>Additional Links:</p>
<ul>
<li><a href="https://blog.trailofbits.com/2019/06/20/getting-2fa-right-in-2019/">Getting 2FA Right in 2019 | Trail of Bits Blog</a></li>
<li><a href="https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring">autoDocstring - Python Docstring Generator - Visual Studio Marketplace</a></li>
<li><a href="https://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings">styleguide | Style guides for Google-originated open-source projects</a></li>
<li><a href="https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html#the-sphinx-docstring-format">Writing docstrings — Sphinx-RTD-Tutorial documentation</a></li>
<li><a href="https://django-ninja.rest-framework.com/">Django Ninja</a></li>
<li><a href="https://github.com/georgesdimitrov/arvo">arvo: Python library for procedural music composition</a></li>
<li><a href="https://www.youtube.com/watch?v=qxB7r4hnEL8">Getting Started with arvo: a Procedural Music Composition Library - YouTube</a></li>
<li><a href="https://web.mit.edu/music21/">music21: a Toolkit for Computer-Aided Musicology</a></li>
<li><a href="https://github.com/cuthbertLab/music21">music21: GitHub</a></li>
<li><a href="https://musescore.org/en">Free music composition and notation software | MuseScore</a></li>
<li><a href="https://www.w3.org/2021/06/musicxml40/tutorial/code-generation/">Code Generation | MusicXML 4.0</a></li>
<li><a href="https://realpython.com/python-gui-tkinter/">Python GUI Programming With Tkinter – Real Python</a></li>
<li><a href="https://www.tcl.tk/">Tcl Developer Site</a></li>
<li><a href="https://docs.python.org/3/library/tkinter.html">tkinter — Python interface to Tcl/Tk — Python 3.10.5 documentation</a></li>
<li><a href="https://github.com/dumistoklus/svg-xsd-schema">svg-xsd-schema: XSD schema for SVG</a></li>
<li><a href="https://developer.mozilla.org/en-US/docs/Web/SVG">SVG: Scalable Vector Graphics | MDN</a></li>
</ul>
<p>Level up your Python skills with our expert-led courses:</p>
<ul>
<li><a href="https://realpython.com/courses/records-sets-ideal-data-structure/">Records and Sets: Selecting the Ideal Data Structure</a></li>
<li><a href="https://realpython.com/courses/documenting-python-code/">Documenting Code in Python</a></li>
<li><a href="https://realpython.com/courses/dicts-arrays-ideal-data-structure/">Dictionaries and Arrays: Selecting the Ideal Data Structure</a></li>
</ul> <p><a rel="payment" href="https://realpython.com/join">Support the podcast & join our community of Pythonistas</a></p>