Project Demo and Details

00:00 Project Demo and Details.

00:05 In this course, you’ll build documentation that’s partly auto-generated from docstrings in your code. The example code package is intentionally simplistic, so you can focus your attention on learning how to use MkDocs and the associated libraries. After you set up your project documentation locally, you’ll learn how to host it on GitHub Pages, so it’ll be available for everyone to see.

00:25 You can use the example project documentation that you’ll build in this course as a blueprint to create documentation for your own Python projects. You’ll build project documentation for a toy package called calculator.

00:39 It will contain only one module, calculations.py, that has a couple of example Python functions. This code doesn’t offer any new functionality and is only meant as a basis to learn how to use existing project code to build your documentation.

00:56 You’ll follow a guideline for project documentation called the Diátaxis documentation framework, which has widespread adoption in a Python community and is used by large projects such as Django and NumPy.

01:09 This system suggests spitting up the documentation into four parts with different orientations: tutorials, which are learning oriented; how-to guides, which are problem-oriented; reference, which is information-oriented; and explanation, which is understanding-oriented.

01:26 Splitting your project documentation into these four different purposes with different orientations will help you create comprehensive documentation for your Python project. From a technical perspective, you’ll build your documentation using three Python packages: MkDocs for building static pages from Markdown, mkdocstrings for auto-generating documentation from docstrings in your code, and Material for MkDocs for styling your documentation.

01:56 When you want to use MkDocs for auto-generating parts of your documentation from your docstrings, you’ll need to add the mkdocstrings package.

02:06 You don’t need to add the Material for MkDocs theme for building your project documentation, but it will help to render the documentation in a user-friendly manner

02:16 To complete this course, you should be comfortable with the following concepts: virtual environments, package management, code documentation, and GitHub repositories.

02:29 If you feel you don’t have all this knowledge, that’s okay. You may well learn what you need as you go by following along with the course. And, as ever, Real Python has you covered.

02:37 If you’d like to learn more about these subjects before continuing with the rest of this course, you can learn how to document a Python project in this course, and you can get up to speed with GitHub with this course.

02:53 Any code that’s seen in this course in the Python REPL will be run using the BPython interpreter, which offers a number of improvements over the standard Python REPL, including color coding. However, all of the code that you see running will work in the standard Python interactive shell, which is accessed typically by typing python from a terminal where your virtual environment has already been activated.

03:17 You’ve now seen the project in action and have an idea of what’s needed to complete it. So in the next section of the course, you’ll make a start by setting everything up ready to start using MkDocs.