Creating Static Pages From Markdown
The index page is the default entry point for your project documentation, and you can edit the text in this file to fit your project landing page. You can also add more Markdown files to the
docs/ folder, and each of them will render into a new page of your documentation.
00:29 As you saw earlier in the course, you’ll follow the structure proposed in the Diátaxis documentation framework, which suggests splitting your documentation into four distinct parts: tutorials, how-to guides, reference, and explanation.
00:45 To set up a structure for your project documentation, create four additional Markdown files representing the different parts. If you’re on macOS or Linux, you can create the files using the command seen on-screen.
The first page that shows up is always
index.md. All remaining pages show up in the order listed in
docs/. Files are listed alphabetically by default, but you’d like to preserve the order proposed by the documentation framework.
You’ve added the file names for all your documentation pages under the
nav element with appropriate indentation. You can now click through your documentation in the intended order as MkDocs serves it to you.
02:30 You might have noticed that each page already has a title, which MkDocs inferred from the filenames. If you don’t like a page’s title, then you can optionally add another element in front of the filename whose title you want to change.
02:54 With the order and titles updated in your settings file, you can now fill your documentation with information about your package. Feel free to practice writing your own documentation pages, or you can use the Markdown files included with the course materials to see an example of how MkDocs does a great job at rendering your Markdown text to a styled webpage. On-screen, you can see some of the contents of the Markdown files that are included with the course materials.
03:27 Keeping project documentation up to date can be challenging, so auto-generating at least part of it can save you time and effort. MkDocs is a static-site generator geared towards writing documentation.
03:39 However, you can’t fetch docstring information for your code using MkDocs alone. You can make it work with an additional package called mkdocstrings. You already installed mkdocstrings into your virtual environment at the start of the course, so you only need to add it as a plugin to your MkDocs configuration file.
Mkdocstrings allows you to insert docstring information right into your Markdown pages. It uses a special syntax of three colons (
:::) followed by the code identifier that you want to document, as seen on-screen.
Because you’ve already written your code documentation in your docstrings, you now only need to add these identifiers to your Markdown documents. The central part of your code reference goes into
reference.md, and you’ll let mkdocstrings add it for you automatically based on the docstrings.
You’ve only added a single line to the Markdown file, but if you view the reference page in your browser, you can see that mkdocstrings gathered all the information from your docstrings in
calculator/calculations.py and has rendered them.
05:11 It also created clickable links in the navigation panel on the right to jump to any function definition with a single click. It’s also generated a collapsible section that contains the source code of the relevant function.
You can continually update the user-facing documentation that you built with MkDocs from your docstrings. Instead of rendering all your module information on the reference page, you can also render just the package docstring that you recorded in
__init__.py by noting the name of your package as the identifier.
06:11 If you integrate mkdocstrings into your project documentation workflow, then you can avoid repetition and reduce the effort needed to keep your documentation up to date. In the next section of the course, you’ll learn how to use MkDocs to create static documentation that works without running a server.
Become a Member to join the conversation.