Creating Your MkDocs Project Structure

00:00 Create Your MkDocs Project Structure. With solid docstrings in your source code, you next want to make your project more accessible to a broad user base.

00:11 Your project will shine more brightly if you can provide user-friendly documentation that’s accessible online. MkDocs is a Python package that allows you to build static pages using Markdown.

00:25 The basic structure of an MkDocs project consists of three main components: your project code, all your Markdown documentation pages inside a docs/ folder, and a configuration file named mkdocs.yml.

00:40 You already have your project code ready to go. Create the other two puzzle pieces next using the handy new command provided by MkDocs.

00:53 This command creates a default project structure for your MkDocs project in the current directory, which the dot (.) at the end of the command references.

01:03 On-screen, you can see the folders and files that were created.

01:09 Soon, you’ll edit index.md and expand your written documentation by adding new Markdown files to the docs/ directory. But first you’ll explore the mkdocs.yml settings file, which tells MkDocs how to handle your project documentation.

01:27 MkDocs uses a YAML file for configuration. When you create a new project using new, MkDocs creates a bare-bones YAML file for you. The default settings file only contains one element, site_name, which defines the default name My Docs for your documentation. Now, of course you don’t want your project to keep that name, so you’ll change it to Calculation Docs instead.

01:53 As a connoisseur of Google’s Material Design, you’ll also want your documentation to look great right away. By adding a second element to your YAML settings file, you can replace the default theme with a popular Material for MkDocs theme, which you installed at the beginning of this course.

02:12 Once you’ve edited the settings file in this way, you can take a look at the current state of your boilerplate documentation by building the site.

02:23 As soon as the terminal tells you that it’s serving the documentation, as seen-on screen, you can view it in your browser. As you can see, MkDocs says that it’s serving the documentation at the address seen on-screen.

02:36 Open a new browser tab and enter that URL. You’ll see the MKDocs boilerplate index page with your custom title, styled with a Material for MkDocs theme. If you want to know where all the text you see is stored, you can open up index.md.

02:55 You can edit this page and see the changes automatically reflected in your browser. While you keep working on your documentation, you can keep going back to the address seen earlier in your browser to view those changes. If you don’t see an update, then stop the server by pressing Control and C with the terminal window in focus and rebuild the site using the mkdocs serve command.

03:21 You’ve made two adaptations in the mkdocs.yml file to change the look and feel of your documentation. However, the content of your docs is still just pre-built boilerplate text that isn’t related to your Python project.

03:34 It’s time to fix that, and you’ll be doing that in the next part of the course.