Unable to build manpages for 9.1.2

[jbfavre]

Hello,
Packaging trafficserver on Debian, I had to disable documentation build a while ago because of an error with sphinxcontrib.plantuml. I recently tried to fix that to be able to provide manpages within the package.

Initial build error was:

Exception occurred:
  File "/usr/lib/python3/dist-packages/docutils/nodes.py", line 2056, in unknown_departure
    raise NotImplementedError(
NotImplementedError: <class 'ManualPageTranslator'> departing unknown node type: plantuml

I'm using Debian version of packages:

• sphinxcontrib.plantuml 0.5 (quite outdated)
• sphinx 4.5.0
• plantuml 1:1.2020.2

Current attempt to get manpages back into the package:

I Use

• sphinxcontrib-plantuml 0.23 (installed with pip)
• sphinx 4.5.0
• plantuml 1:1.2020.2 (also tested with 1.2018.1 from ci.trafficserver.apache.org)

I got a lot of error and warning, but at least the build ends "successfully".
However, manpages are not generated:

$ ls docbuild/man/
apachetrafficserver.1

I attached full log output.
Does anyone faces the same issue ?

I'm considering building them locally, adding them as static content into the package and disable automatic documentation build. But, for this to work, I still need a solution to get manpages built locally.

make_man.log

[jbfavre]

Made some progress in the investigation.
It turns out that every documentation is generated in a single apachetrafficserver.1 file.

Having a deeper look, I can't understand how manpages.py output is used by sphinx.
As I understand it, manpages.py is supposed to provided the list of manpages to generate through the global man_pages variable.

This is why it's not defined in conf.py.
Indeed, copying/pasting the man_pages definition from manpages.py to conf.py makes the every man pages to be generated.

Will look to find a way to call or include manpages.py from conf.py