Creating Static Pages From Markdown

Building Python Project Documentation With MkDocs Darren Jones 06:30

00:00 Create Static Pages From Markdown. As you’ve already seen, setting up a new MkDocs project creates a default index.md file in the docs/ folder.

00:12 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.

01:11 And if you’re on Windows Terminal, you can create the files using this command.

01:28 After adding these four files, your docs/ folder will contain five Markdown files, as seen on-screen. MkDocs builds every Markdown file that it finds in docs/ as a separate page.

01:41 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.

01:58 To determine a custom order for your documentation pages, you need to add the nav element to your settings file and list all files in the order in which you want to show them.

02:17 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.

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.

04:03 By adding mkdocstrings as a list item to the plugins element, you activated the plugin for this project.

04:12 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.

04:25 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.

04:47 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:00 You may notice that mkdocstrings pulled information from your type hints and the function and module-level docstrings and now presents them to you in a user-friendly manner.

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.

05:25 The work that you did when writing your docstrings is paying off. The best part is that you’ll only need to keep the documentation right inside your codebase up to date.

05:34 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:01 If you need to update your docstrings because you changed your project code, then you just need to rebuild your documentation to propagate those changes.

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.

512jay on Oct. 18, 2023

Getting the the following error

ModuleNotFoundError: No module named ‘mkdocstrings.handlers.python’

When attempting to create the static reference code with mkdocstrings automatically, I think it has worked in the past.

Mariya Sakalova on March 18, 2024

@512jay I run pip install mkdocstrings-python. It worked for me.

k-taylor on July 25, 2024

Adding

plugins:
 - mkdocstrings

to mkdocs.yml also gives me:

ModuleNotFoundError: No module named 'mkdocstrings.handlers.python'

when trying to run mkdocs serve.

I have mkdocstrings-python installed:

k-taylor on July 28, 2024

It seems like the version of mkdocstrings was the issue. Installing version 0.18 seemed to fix it.

python -m pip install "mkdocstrings[python]"==0.18

I went from:

mkdocstrings               0.19.0
mkdocstrings-python        0.8.3

mkdocstrings               0.18.0
mkdocstrings-python        0.6.6
mkdocstrings-python-legacy 0.2.2

and now mkdocs serve works just fine.

k-taylor on July 28, 2024

Also in the .yml file:

plugins: - mkdocstrings

didn’t work. I had to add:

lugins: - mkdocstrings: handlers: python: paths: [/home/my_name/my_code/MKdocs]

or else it would serve mkdocs ok, and I’d get no errors but no docstrings actually got imported.

Become a Member to join the conversation.