Subject: Issue with documentation setup - matplotlib installation in venv

RishitModi · November 3, 2025, 9:58am

Hello Community,
I'm excited to start contributing to Plone and decided to begin by setting up the documentation on my local machine.

My system info:
Windows wsl with Ubuntu distro
with all the prerequisites already installed for the setup

I was carefully following the guidelines on the "Set up, build, and check the quality of documentation" page. However, when running the make livehtml command (or the initial setup step), I encountered an installation error related to matplotlib.
Here is the error I received:
“Matplotlib is missing”

It seems the process failed to install matplotlib correctly within the virtual environment.
My Workaround
To resolve this, I performed the following steps:

I separately installed Matplotlib into the venv
After that, I ran the make livehtml command again, and the build completed successfully without any errors.

I just wanted to check whether this is an expected step that I might have missed, or if this points to a potential issue in the setup script?
If it's the latter, I'd be happy to help create a patch for requirements.txt
Thanks for your guidance!

stevepiercy · November 3, 2025, 10:22am

I assume you followed this guide?

matplotlib is not a requirement.

Please provide the full stacktrace as text, not an image. Discourse allows you to paste code blocks using the </> button.

Include the steps you followed to get the stacktrace.

You can also try to obliterate both the virtual environment and documentation build, and rebuild with the following command from the root of the documentation repository.

make distclean clean build

Please let me know. Thank you!

RishitModi · November 3, 2025, 3:09pm

Hi @stevepiercy

Thank you for getting back to me.

Yes, you are correct, the link you provided is the exact guide I have been following.

I ran the make distclean clean build command from the root of the repository as you suggested. Unfortunately,it produced the same error & warnings

As requested, here is the stacktrace focusing on the part where errors and warnings are displayed(the character limit on the forum does not allow me to give you the entire stacktrace and the upload option does not allow .txt files)

[sphinx-autobuild] > python -m sphinx build -b html . ../_build/html
Running Sphinx v8.2.3
loading translations [en]... done
matplotlib is not installed, social cards will not be generated
myst v4.0.1: MdParserConfig(commonmark_only=False, gfm_only=False, enable_extensions={'substitution', 'linkify', 'deflist', 'colon_fence', 'strikethrough', 'html_image', 'attrs_inline', 'attrs_block'}, disable_syntax=[], all_links_external=False, links_external_new_tab=False, url_schemes=('http', 'https', 'mailto', 'ftp'), ref_domains=None, fence_as_directive=set(), number_code_blocks=[], title_to_header=False, heading_anchors=0, heading_slug_func=None, html_meta={}, footnote_sort=True, footnote_transition=True, words_per_minute=200, substitutions={postman_basic_auth: ..., postman_headers: ..., postman_request: ..., postman_response: ..., postman_retain_headers: ..., fawrench: ..., SUPPORTED_PYTHON_VERSIONS_PLONE60: ..., SUPPORTED_PYTHON_VERSIONS_PLONE61: ..., SUPPORTED_PYTHON_VERSIONS_PLONE62: ...}, linkify_fuzzy_links=True, dmath_allow_labels=True, dmath_allow_space=True, dmath_allow_digits=True, dmath_double_inline=False, update_mathjax=True, mathjax_classes='tex2jax_process|mathjax_process|math|output_area', enable_checkboxes=False, suppress_warnings=[], highlight_code_blocks=True)
[autosummary] generating autosummary for: _inc/_continuous-integration.md, _inc/_create-classic-ui-instance.md, _inc/_install-browser-reqs-classic-ui.md, _inc/_install-pillow.md, _inc/_install-python-plone61.md, admin-guide/add-ons.md, admin-guide/add-site.md, admin-guide/backup-restore-plone-buildout.md, admin-guide/configure-zope.md, admin-guide/export-import.md, ..., volto/theming/theming-a-base-theme.md, volto/theming/theming-engine.md, volto/theming/theming-strategy.md, volto/theming/using-third-party-themes.md, volto/tutorials/index.md, volto/upgrade-guide/index.md, volto/user-manual/blocks.md, volto/user-manual/copy-paste-blocks.md, volto/user-manual/index.md, volto/user-manual/links-to-item.md
loading intersphinx inventory 'plone' from https://6.docs.plone.org/objects.inv ...
loading intersphinx inventory 'plone5' from https://5.docs.plone.org/objects.inv ...
loading intersphinx inventory 'python' from https://docs.python.org/3/objects.inv ...
loading intersphinx inventory 'training' from https://training.plone.org/objects.inv ...
loading intersphinx inventory 'training-2022' from https://2022.training.plone.org/objects.inv ...
loading intersphinx inventory 'training-2023' from https://2023.training.plone.org/objects.inv ...
loading intersphinx inventory 'training-2024' from https://2024.training.plone.org/objects.inv ...
building [mo]: targets for 0 po files that are out of date
writing output...
building [html]: targets for 409 source files that are out of date
updating environment: [new config] 409 added, 0 changed, 0 removed
reading sources... [100%] volto/user-manual/links-to-item
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/sending-email.md:: ERROR: Error parsing meta tag attribute "description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/sending-email.md:: ERROR: Error parsing meta tag attribute "property=og:description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/sending-email.md:: ERROR: Error parsing meta tag attribute "property=og:title": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/sending-email.md:: ERROR: Error parsing meta tag attribute "keywords": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/users-groups.md:: ERROR: Error parsing meta tag attribute "description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/users-groups.md:: ERROR: Error parsing meta tag attribute "property=og:description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/users-groups.md:: ERROR: Error parsing meta tag attribute "property=og:title": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/backend/users-groups.md:: ERROR: Error parsing meta tag attribute "keywords": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/recipes.md:: ERROR: Error parsing meta tag attribute "description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/recipes.md:: ERROR: Error parsing meta tag attribute "property=og:description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/recipes.md:: ERROR: Error parsing meta tag attribute "property=og:title": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/recipes.md:: ERROR: Error parsing meta tag attribute "keywords": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/templates.md:: ERROR: Error parsing meta tag attribute "description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/templates.md:: ERROR: Error parsing meta tag attribute "property=og:description": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/templates.md:: ERROR: Error parsing meta tag attribute "property=og:title": No content. [docutils]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/classic-ui/templates.md:: ERROR: Error parsing meta tag attribute "keywords": No content. [docutils]
looking for now-outdated files... none found
pickling environment... done
checking consistency... /mnt/c/Users/BJMODI/Desktop/documentation/docs/glossary.md: document is referenced in multiple toctrees: ['index', 'plone.restapi/docs/source/index'], selecting: plone.restapi/docs/source/index <- glossary
done
preparing documents... done
copying assets...
copying downloadable files... [100%] ../submodules/volto/docs/source/contributing/Quanta.pdf
copying static files...
Writing evaluated template result to /mnt/c/Users/BJMODI/Desktop/documentation/_build/html/_static/basic.css
Writing evaluated template result to /mnt/c/Users/BJMODI/Desktop/documentation/_build/html/_static/documentation_options.js
Writing evaluated template result to /mnt/c/Users/BJMODI/Desktop/documentation/_build/html/_static/language_data.js
Writing evaluated template result to /mnt/c/Users/BJMODI/Desktop/documentation/_build/html/_static/copybutton.js
copying static files: done
copying extra files...
copying extra files: done
copying assets: done
writing output... [100%] volto/user-manual/links-to-item
/mnt/c/Users/BJMODI/Desktop/documentation/docs/volto/development/i18n.md:118: WARNING: Lexing literal_block '// When using a component:\n@injectIntl\nclass TeaserImage extends Component {\n  // ...\n}\n' as "js" resulted in an error at token: '@'. Retrying in relaxed mode. [misc.highlighting_failure]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/volto/theming/create-theme-add-on.md:110: WARNING: Lexing literal_block '/*******************************\n        Theme Selection\n*******************************/\n\n/* To override a theme for an individual element specify theme name below */\n\n/* Global */\n@site        : \'pastanaga\';\n@reset       : \'pastanaga\';\n\n/* Elements */\n@button      : \'pastanaga\';\n@container   : \'pastanaga\';\n@divider     : \'pastanaga\';\n@flag        : \'pastanaga\';\n@header      : \'pastanaga\';\n@icon        : \'pastanaga\';\n@image       : \'pastanaga\';\n@input       : \'pastanaga\';\n@label       : \'pastanaga\';\n@list        : \'pastanaga\';\n@loader      : \'pastanaga\';\n@placeholder : \'pastanaga\';\n@rail        : \'pastanaga\';\n@reveal      : \'pastanaga\';\n@segment     : \'pastanaga\';\n@step        : \'pastanaga\';\n\n/* Collections */\n@breadcrumb  : \'pastanaga\';\n@form        : \'pastanaga\';\n@grid        : \'pastanaga\';\n@menu        : \'pastanaga\';\n@message     : \'pastanaga\';\n@table       : \'pastanaga\';\n\n/* Modules */\n@accordion   : \'pastanaga\';\n@checkbox    : \'pastanaga\';\n@dimmer      : \'pastanaga\';\n@dropdown    : \'pastanaga\';\n@embed       : \'pastanaga\';\n@modal       : \'pastanaga\';\n@nag         : \'pastanaga\';\n@popup       : \'pastanaga\';\n@progress    : \'pastanaga\';\n@rating      : \'pastanaga\';\n@search      : \'pastanaga\';\n@shape       : \'pastanaga\';\n@sidebar     : \'pastanaga\';\n@sticky      : \'pastanaga\';\n@tab         : \'pastanaga\';\n@transition  : \'pastanaga\';\n\n/* Views */\n@ad          : \'pastanaga\';\n@card        : \'pastanaga\';\n@comment     : \'pastanaga\';\n@feed        : \'pastanaga\';\n@item        : \'pastanaga\';\n@statistic   : \'pastanaga\';\n\n/* Extras */\n@main        : \'pastanaga\';\n@custom      : \'pastanaga\';\n\n/*******************************\n            Folders\n*******************************/\n\n/* Path to theme packages */\n@themesFolder : \'~volto-themes\';\n\n/* Path to site override folder */\n@siteFolder  : "<name_of_your_theme>/theme";\n\n/*******************************\n          Import Theme\n*******************************/\n\n@import (multiple) "~semantic-ui-less/theme.less";\n@fontPath : "~volto-themes/@{theme}/assets/fonts";\n\n.loadAddonOverrides() {\n  @import (optional) "@{siteFolder}/@{addon}/@{addontype}s/@{addonelement}.overrides";\n}\n\n/* End Config */' as "less" resulted in an error at token: '@'. Retrying in relaxed mode. [misc.highlighting_failure]
/mnt/c/Users/BJMODI/Desktop/documentation/docs/volto/theming/custom-styling.md:105: WARNING: Lexing literal_block '.loadThemeFonts() {\n    @import "./typography.css";\n}\n' as "less" resulted in an error at token: '@'. Retrying in relaxed mode. [misc.highlighting_failure]
generating indices... genindex http-routingtable py-modindex done

For complete context, here are the exact steps I followed from the beginning, which led to this error:

Set up Windows Subsystem for Linux (WSL).
Installed the required versions of Python, Graphviz, and GNU Make.

Ran the following commands inside WSL, as per the documentation:

git clone https://github.com/plone/documentation.git
cd documentation
make livehtml

This make livehtml command is what triggered the error initially, and the make distclean clean build command triggers it again.

It seems the matplotlib dependency issue is persisting despite the clean build. Please let me know if there's any other information I can provide to help troubleshoot.

Thanks!

stevepiercy · November 3, 2025, 6:57pm

matplotlib is not installed, social cards will not be generated

That’s not an error, but a warning.

There are several other warnings in the console output. That’s not a stacktrace.

In any case, if you can view the HTML as the last line in the console indicates, then the docs built successfully.

Also, I gave you the incorrect build command, and should have s/build/livehtml. For this one, you don’t need to remove the dist or docs builds, but this one will give you a live preview of the built docs, and reload the page while you edit it.

make livehtml

Please let me know. Thank you!

RishitModi · November 7, 2025, 7:39pm

Hi @stevepiercy,

Alright, that makes sense.

Yes, I can confirm I'm able to view the HTML as the last line in the console indicates.

Great to know the setup is successful! I'm all set and will start looking for ways to contribute.

Thanks again for your help!