Rectifying Your MkDocs Setup After Upgrading Python

 

Photo By - Brian Lundquist on Unsplash

After I upgraded all my Homebrew local packages, which included Python and MkDocs, I ran into a series of errors when trying to build MkDocs and start the MkDocs server locally.

A MkDocs setup generally needs specific Python packages to fulfill the required dependencies. Therefore, when you upgrade your Python version, you may need to reinstall all the Python packages, which correspond to the MkDocs dependencies, to get your local MkDocs setup working correctly.

Let’s see how you can resolve these MkDocs errors.

Resolving errors when working with the WSO2 API-M related MkDocs setup

The following are the steps that I followed to get my local WSO2 API Manager (WSO2 API-M) documentation related MkDocs setup back to normal. Note that I used the pip3 command because I was using Python 3.x.

1. Navigate to the docs-apim/en/ directory in your local folder.
   Ignore the existing installations and install the required dependencies.
   
   pip3 install --ignore-installed -r requirements.txt
   
   The requirements.txt file defines all the MkDocs dependencies together with their versions that you need to install. Therefore, you can execute a single command to install multiple Python packages with specific versions.
   
   
2. Optionally, install the required mkdocs-material theme.
   I had to run this command as the correct version of the mkdocs-material theme did not get installed in the previous step.
   
   pip3 install --force-reinstall mkdocs-material===4.5.1
   
   
3. Optionally, check the versions of the dependencies that you installed.
   
   Format:
   pip3 show <package-name> --version
   
   Example:
   pip3 show mkdocs-material --version
   
   
4. Optionally, remove stale files and build MkDocs.
   
   mkdocs build --clean
   
   
5. Start the MkDocs server as usual.
   
   mkdocs serve

Resolving errors in an isolated manner

Suppose you are working with a different set of requirements, and you get one of the following errors after you upgraded Python. Then you can fix the specific error by executing the following command to reinstall the respective Python package to use the pip that pairs with the appropriate interpreter.

Format:
python<x> -m pip install <package>===<version>

Replace the placeholder values as follows:

• <x> - Python version.
• <package> - Replace based on the following table.
• <version> - Replace based on the actual MkDocs dependency version that is supported.

Example:
python3.9 -m pip install mkdocs-material===4.5.1

Error	Package
zsh: /usr/local/bin/mkdocs: bad interpreter: /usr/local/opt/python/bin/python3.7: no such file or directory	mkdocs
MkDocs encountered as error parsing the configuration file: while constructing a Python object cannot find module 'pymdownx.emoji' (No module named 'pymdownx')	pymdown-extensions
ERROR - Config value: 'markdown_extensions'. Error: Failed loading extension "markdown_include.include".	markdown-include
ERROR - Config value: 'plugins'. Error: The "markdownextradata" plugin is not installed	mkdocs-markdownextradata-plugin
ERROR,-,Config value: 'plugins'. Error: The "exclude" plugin is not installed	mkdocs-exclude
ERROR - Config value: 'plugins'. Error: The "redirects" plugin is not installed	mkdocs-redirects
ERROR - Config value: 'theme'. Error: Unrecognised theme name: 'material'. The available installed themes are: mkdocs, readthedocs	mkdocs-material

Acknowledgments

• A huge thank you to goes out to Shani Ranasinghe for helping me troubleshoot this issue and identify the solution with regard to the WSO2 API Manager GitHub-based documentation.
• A big thank you goes out to Raarzer  as well for the comment on Reddit, which ended up being useful to resolve the issue that I faced.