Stream: docs

Topic: Build Sphinx guides on Linux

Jan van Mansum (Jun 27 2025 at 10:47):

I managed to build the Sphinx guides locally on Linux Mint. There are no instructions for this in doc/sphinx-guides/HOWTO-SPHINX-INSTALL.txt. Should I create PR to add those?

Basically, I did a pip install and then had to install some extra modules to make "make html" work:

pip install sphinx
pip install sphinx-icon
pip install sphinx-jquery
pip install sphinxcontrib-jquery
pip install myst-parser
pip install sphinx-tabs

Also, I installed graphviz

Let me know, if/where this should be added to the docs.

Philip Durbin 🚀 (Jun 27 2025 at 11:44):

Hmm, I've considered deleting that README. The instructions that we actively edit are here: https://guides.dataverse.org/en/6.6/contributor/documentation.html#building-the-guides-with-sphinx

Philip Durbin 🚀 (Jun 27 2025 at 11:45):

Can you please tell us if those are accurate? If you'd like to make any edits, the file is https://github.com/IQSS/dataverse/blob/develop/doc/sphinx-guides/source/contributor/documentation.md

Jan van Mansum (Jun 27 2025 at 12:32):

Yes, that works. Pity I didn't find that one before the README; it would have saved some time. Please, remove the README.

Philip Durbin 🚀 (Jun 27 2025 at 13:03):

@Jan van Mansum please feel free to open a PR to delete it!

Jan van Mansum (Jun 27 2025 at 13:17):

Sure, here you are https://github.com/IQSS/dataverse/pull/11598

Philip Durbin 🚀 (Jun 27 2025 at 13:19):

Approved! Thanks!

Oliver Bertuch (Jun 27 2025 at 13:21):

Potentially dumb question: would it make sense to create a container image with all the necessary Sphinx bits and use the Docker Maven Plugin to enable building the documentation? We could also look into reusing the "Read The Docs" container images for this purpose.

Philip Durbin 🚀 (Jun 27 2025 at 13:24):

@Oliver Bertuch we do have this already: https://guides.dataverse.org/en/6.6/contributor/documentation.html#building-the-guides-with-a-sphinx-docker-container-and-a-makefile

Oliver Bertuch (Jun 27 2025 at 13:25):

Yeah just wondering if it might help to just use mvn site.

Oliver Bertuch (Jun 27 2025 at 13:26):

Make the docs a Maven module - but of course still allow for different ways to build it.

Oliver Bertuch (Jun 27 2025 at 13:26):

Just a matter of convenience. Not everybody has Make installed ;-)

Philip Durbin 🚀 (Jun 27 2025 at 13:27):

That's what https://guides.dataverse.org/en/6.6/contributor/documentation.html#building-the-guides-with-a-sphinx-docker-container-and-cli is for. No make required. :smile:

Philip Durbin 🚀 (Jun 27 2025 at 13:35):

I probably wouldn't use the mvn thing, but if you'll use it, please feel free to make a PR.

Last updated: Nov 01 2025 at 14:11 UTC