freeipa

#9148 documentation build fails in readthedocs
Closed: fixed by abbra. Opened by abbra.

Closed: fixed
Reopen Issue

Our documentation environment is outdated and fails when a new mistune markdown parser version is used automatically. This causes failure to set up m2r and the whole documentation build process fails:

https://readthedocs.org/projects/freeipa/builds/16805151/

Running Sphinx v2.4.5
loading translations [en]... done
Traceback (most recent call last):
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/site-packages/sphinx/cmd/build.py", line 275, in build_main
    args.tags, args.verbosity, args.jobs, args.keep_going)
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 245, in __init__
    self.setup_extension(extension)
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/site-packages/sphinx/application.py", line 397, in setup_extension
    self.registry.load_extension(self, extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/site-packages/sphinx/registry.py", line 453, in load_extension
    mod = import_module(extname)
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/importlib/__init__.py", line 127, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1006, in _gcd_import
  File "<frozen importlib._bootstrap>", line 983, in _find_and_load
  File "<frozen importlib._bootstrap>", line 967, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 677, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 728, in exec_module
  File "<frozen importlib._bootstrap>", line 219, in _call_with_frames_removed
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/site-packages/m2r.py", line 59, in <module>
    class RestBlockGrammar(mistune.BlockGrammar):
AttributeError: module 'mistune' has no attribute 'BlockGrammar'
Exception occurred:
  File "/home/docs/checkouts/readthedocs.org/user_builds/freeipa/envs/latest/lib/python3.7/site-packages/m2r.py", line 59, in <module>
    class RestBlockGrammar(mistune.BlockGrammar):
AttributeError: module 'mistune' has no attribute 'BlockGrammar'

It is possible to update to Sphinx 4.5 and also switch to m2r2, an updated fork of m2r to fix these issues.

For external IdP design docs we also need plantuml support, which needs to install plantuml and fonts to the readthedocs environment. This is possible by adding .readthedocs.yaml configuration file.

master:

  • 10b4e131a1d0fee48a6cdfbe94044a39621298f2 doc: migrate to m2r2 and newer sphinx, add plantuml to venv
  • 4a7cc3467c36f304a7b2ab4593b5da4aacaecb73 docs: add plantuml and use virtual environment to generate docs
  • cfe4d7c146f33d6b1d91b16173907a66e15720e6 docs: add the readthedocs configuration

ipa-4-9:

  • de918aea190401183da4742fc9d56101a13f1b17 doc: migrate to m2r2 and newer sphinx, add plantuml to venv
  • 7ddef72fbbf779da32660d54389d68a7c3b35a1a docs: add plantuml and use virtual environment to generate docs
  • 68c20846cf80eb2d46a05e0f8879ddfbd19fbbec docs: add the readthedocs configuration
  • ffd8f14af2a1d2d1bce9011473449706902d884d docs: update Sphinx requirements in ipasphinx package
  • 5ea1866f1bdea4e20894906e7dbdbde27f9715cd docs: force sphinx version above 3.0 to avoid caching in RTD

Metadata Update from @abbra:
- Issue close_status updated to: fixed
- Issue status updated to: Closed (was: Open)
Metadata
None
None
None
None
None
Static archive. pagure.io was sunset in 2026; this is a read-only snapshot.
Red Hat Logo

Fedora is sponsored by Red Hat. Learn more about the relationship between Red Hat and Fedora »

© Red Hat, Inc. and others.