Hello, I've had a discussion on docutils mailing list about this issue. Short story: we currently use docutils Inliner monkey patching which is likely to break things whenever docutils changes its API. This change happenned in 0.13.0
A more stable way of building ATS doc would be to use classic docutils roles, ie writing TS issues like ":TS: XXXX" instead of "(TS-XXXX)"and define a custom role which is supported, whereas our current way of monkey patching docutils Inliner isn't. I managed to build trafficserver against docutils 0.13.1, but this require a patch for both trafficserver & docutils. Discussion is still ongoing to know wether the new behaviour is buggy or not, and wether docutils patch should be included in next release or not. In the mean time, I'll work on implementing the docutils custom role. I'll open a github PR as soon as the doc refacto is completed. Trafficserver is about to be removed from Debian within 2 weeks (stable freeze is coming and Trafficserver build currently fails because of the doc) and I'm not sure docutils will be updated until then. Cheers, Jean Baptiste > The exception I get comes from code introduced 2 years and half ago > (commit 8ec35f2c7). > > Python docutils 0.13.1, which entrered Debian unstable on 2016-12-11, > breaks this piece of code. > > Trafficserver entered Debian unstable on 2016-11-29, which means build > was OK. > > I can't find any commit modifying doc/conf.py since the one you > mentionned which fix anything. > > Cheers, > Jean Baptiste Favre > > > On 30/12/2016 16:30, Alan Carroll wrote: >> This is a known issue, caused by using some additional features in Sphinx. >> There are a number of commits on master to address the issue if you want to >> cherry pick them back. I would start with commit 037648 which I think fixes >> this particular problem. Looks for commits with a description of "Doc: ..." >> for other fixes. I think you also need at least version 1.3 of Sphinx to >> successfully build the documentation. >> >> >> On Friday, December 30, 2016 7:09 AM, Jean Baptiste Favre >> <webmas...@jbfavre.org> wrote: >> >> >> Hello, >> Trying to build ATS 7.0.0 with python docutils 0.13.1 on Debian fails >> with following error: >> >> Making all in doc >> make[2]: Entering directory '/home/debocker/source/build/doc' >> PAPEROPT_a4="-D latex_paper_size=a4" PAPEROPT_letter="-D >> latex_paper_size=letter" PAPER="letter" ./sbuild sphinx-build -c . -d >> docbuild/doctrees -b man . docbuild/man >> Running Sphinx v1.4.9 >> making output directory... >> WARNING: sphinx.ext.pngmath has been deprecated. Please use >> sphinx.ext.imgmath instead. >> loading pickled environment... not yet created >> building [mo]: targets for 0 po files that are out of date >> building [man]: all manpages >> updating environment: 456 added, 0 changed, 0 removed >> reading sources... [ 0%] admin-guide/configuration/cache-basics.en >> >> Exception occurred: >> File "conf.py", line 185, in __init__ >> start_string_prefix=self.start_string_prefix, >> AttributeError: Inliner instance has no attribute 'start_string_prefix' >> The full traceback has been saved in /tmp/sphinx-err-5iq_t9.log, if you >> want to report the issue to the developers. >> Please also report this if it was a user error, so that a better error >> message can be provided next time. >> A bug report can be filed in the tracker at >> <https://github.com/sphinx-doc/sphinx/issues>. Thanks! >> Makefile:998: recipe for target 'man' failed >> make[2]: Leaving directory '/home/debocker/source/build/doc' >> make[2]: *** [man] Error 1 >> make[1]: *** [all-recursive] Error 1 >> >> I tracked it down to docutils/parsers/rst/states.py [1] which changed >> between 0.12 & 0.13.1 >> start_string_prefix is not defined anymore at Inliner init. We have to >> call init_cutomizations method, but I can't figure out the setting >> structure. >> >> Cheers, >> Jean Baptiste Favre >> >> [1]: >> https://fossies.org/diffs/docutils/0.12_vs_0.13.1/docutils/parsers/rst/states.py-diff.html
