Building guides: Python 3.10 required, try Docker first, custom titles, other tweaks #11831
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
cmbz
added
FY26 Sprint 6
This was referenced Sep 25, 2025
pdurbin
force-pushed
the
doc-contrib
branch
from
658e2a6 to
3ea1ef2
Compare
stevenwinship
moved this from Ready for Review ⏩
to In Review 🔎
in IQSS Dataverse Project
| `docker run -it --rm -v $(pwd):/docs sphinxdoc/sphinx:7.2.6 bash -c "cd doc/sphinx-guides && pip3 install -r requirements.txt && make html"` | ||
|
|
||
| ### Installing GraphViz | ||
| If all goes well, you should be able open `doc/sphinx-guides/build/html/index.html` to see the guides you just built. |
Contributor
There was a problem hiding this comment.
change to: be able to open
This comment was marked as duplicate.
This comment was marked as duplicate.
Sorry, something went wrong.
pdurbin
changed the title
stevenwinship
approved these changes
Oct 16, 2025
github-project-automation
bot
moved this from In Review 🔎
to Ready for QA ⏩
in IQSS Dataverse Project
Contributor
|
looks good to me - merging |
github-project-automation
bot
moved this from Ready for QA ⏩
to Merged 🚀
in IQSS Dataverse Project
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
How to preview this change
Go to https://dataverse-guide--11831.org.readthedocs.build/en/11831/contributor/documentation.html
What this PR does / why we need it:
My laptop got wiped and I learned that Python 3.10 is required these days (due to Sphinx-Substitution-Extensions being added in #11477). I made sure this is mentioned.
Also, I've talked on and off with @DieuwertjeBloemen about running Sphinx locally. I rewrote the "installing locally" section and suggested trying Docker first.
Finally, I added a tip about how to make a custom title when linking from a .md file.
Which issue(s) this PR closes:
None.
Special notes for your reviewer:
I'd be happy to add Python 3.10 to requirements.txt but I don't think this is supported.
As to how to make a pull request, these docs are still punting to the main developer docs. I guess that's ok but I'm open to maintaining a simplified version here.
Also, should the contributor clone the main repo or their fork? And if they clone their fork, how do they pull the latest from upstream? I like how Zulip is very prescriptive on what they want you to do. See https://zulip.readthedocs.io/en/latest/git/cloning.html#get-zulip-code and https://zulip.readthedocs.io/en/latest/git/using.html#keep-your-fork-up-to-date
Related:
make docs-htmlworking #11830