Python module pygment is really needed by gtk-doc-1.30

[Pierre Labastie]

When building libical:

[...]
Scanning dependencies of target documentation
[ 98%] Generating xml/libical-glib-doc.bottom
unknown:0: warning: Value descriptions for ICalParameterKind are missing in source code comment block.
[... several lines similar to the above ...]
[ 98%] Generating libical-glib documentation
[100%] Generating libical-glib documentation
Traceback (most recent call last):
  File "/usr/bin/gtkdoc-fixxref", line 28, in <module>
    from gtkdoc import common, config, fixxref
  File "/usr/share/gtk-doc/python/gtkdoc/fixxref.py", line 28, in <module>
    from . import common, highlight
  File "/usr/share/gtk-doc/python/gtkdoc/highlight.py", line 28, in <module>
    from pygments import highlight
ModuleNotFoundError: No module named 'pygments'
make[2]: *** [doc/reference/libical-glib/CMakeFiles/documentation.dir/build.make:58: doc/reference/libical-glib/CMakeFiles/documentation] Error 1
make[1]: *** [CMakeFiles/Makefile2:1335: doc/reference/libical-glib/CMakeFiles/documentation.dir/all] Error 2
make: *** [Makefile:141: all] Error 2

So looks like the Python module pygments:

• should be recommended for gtk-doc
• should be in the book (I think only the P3 module is needed)

[Pierre Labastie]

As usual, upstreamgtk-doc have introduced regressions... The libical documentation does not build, even with pygments present:

[ 98%] Generating libical-glib documentation
[100%] Generating libical-glib documentation
Traceback (most recent call last):
  File "/usr/bin/gtkdoc-fixxref", line 57, in <module>
    fixxref.Run(options)
  File "/usr/share/gtk-doc/python/gtkdoc/fixxref.py", line 54, in Run
    highlight.append_style_defs(os.path.join(options.module_dir, 'style.css'))
  File "/usr/share/gtk-doc/python/gtkdoc/highlight.py", line 50, in append_style_defs
    os.chmod(css_file_name, stat.S_IWRITE)
FileNotFoundError: [Errno 2] No such file or directory: './style.css'
make[2]: *** [doc/reference/libical-glib/CMakeFiles/documentation.dir/build.make:58: doc/reference/libical-glib/CMakeFiles/documentation] Error 1
make[1]: *** [CMakeFiles/Makefile2:1335: doc/reference/libical-glib/CMakeFiles/documentation.dir/all] Error 2
make: *** [Makefile:141: all] Error 2

So gtkdoc-fixxdep does not find the style.css file, which has been created by gtk-doc-mkhtml... This is a problem with gtk-doc: I've verified on the gtk-doc documentation, the libical build system does exactly what is recommended by the docs.

OTOH, Pygments will remain needed for this stuff, even when upstream fixes their code. So I'll still add that module to the book. But, I'll disable generating doc for libical (pass -DICAL_BUILD_DOCS=false to cmake).

[Pierre Labastie]

Note that make docs is not available anymore if -DICAL_BUILD_DOCS=false is passed.

[Pierre Labastie]

Fixed at r21585

[Bruce Dubbs]

Milestone renamed