You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Jean Baptiste Favre <we...@jbfavre.org> on 2017/01/03 10:32:18 UTC
Re: ATS doesn't build with python docutils 0.13.1
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 <we...@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
Re: ATS doesn't build with python docutils 0.13.1
Posted by Jack Bates <6n...@nottheoilrig.com>.
Will do.
On 06/01/17 11:04 AM, Alan Carroll wrote:
> Jack, can you put up a pull request? I'm internally debating whether we want the auto TS-XXXX linkage or not, so I think it would be good to have a PR on which to discuss it. Thanks.
>
>
> On Friday, January 6, 2017 10:39 AM, Jack Bates <6n...@nottheoilrig.com> wrote:
>
>
> Thanks for fixing this Jean Baptiste!
> I'd like to maintain the custom autolinker,
> would you mind if I restored that code and applied the fix below?
> After this fix, it works with Docutils 1.3 and 1.2.
> I realize it would've been much better if I'd had this ready at the
> beginning of the week ...
>
> --- a/doc/conf.py
> +++ b/doc/conf.py
> @@ -166,9 +166,11 @@ pygments_style = 'sphinx'
> nitpicky=1
>
> # Autolink issue references
> +# See Customizing the Parser in the docutils.parsers.rst module.
>
> from docutils import nodes
> from docutils.parsers.rst import states
> +from docutils.utils import punctuation_chars
> from docutils.utils import unescape
>
> # Customize parser.inliner in the only way that Sphinx supports.
> @@ -180,9 +182,34 @@ from docutils.utils import unescape
>
> BaseInliner = states.Inliner
> class Inliner(BaseInliner):
> + if hasattr(states.Inliner, 'init_customizations'):
> + def init_customizations(self, settings):
> + self.__class__ = BaseInliner
> + BaseInliner.init_customizations(self, settings)
> + self.__class__ = Inliner
> +
> + # Copied from states.Inliner.init_customizations().
> + if settings.character_level_inline_markup:
> + self.start_string_prefix = u'(^|(?<!\x00))'
> + self.end_string_suffix = u''
> + else:
> + self.start_string_prefix = (u'(^|(?<=\\s|[%s%s]))' %
> + (punctuation_chars.openers,
> + punctuation_chars.delimiters))
> + self.end_string_suffix = (u'($|(?=\\s|[\x00%s%s%s]))' %
> + (punctuation_chars.closing_delimiters,
> + punctuation_chars.delimiters,
> + punctuation_chars.closers))
> +
> + self.init()
> + else:
> def __init__(self):
> BaseInliner.__init__(self)
> + self.init()
>
> + # Called from __init__() in Docutils < 1.3, otherwise from
> + # init_customizations(), which was added in Docutils 1.3.
> + def init(self):
> issue_pattern = re.compile(u'''
> {start_string_prefix}
> TS-\d+
>
> On 04/01/17 08:08 AM, Jean Baptiste Favre wrote:
>> Hello,
>> I've updated my PR on github.
>> We can now manage both Jira issues with ":ts:jira:`XXXX`" syntax, as
>> well as github issues with ":ts:github:`XXXX`" syntax.
>>
>> Now, Trafficserver build succeed with doctuils 0.13.1.
>> Please note that I did not test yet build against docutils 0.12.
>> I'll in the coming days (docutils 0.12 is in Debian stable only).
>>
>> Cheers,
>> Jean Baptiste
>>
>>
>> On 03/01/2017 15:11, Jean Baptiste Favre wrote:
>>> Hello Alan,
>>> Thanks for the info.
>>> I had a look in traffic_server.py, but to quick to notice about :ts:cv: :-/
>>>
>>> given the Jira to Github transition announced by Brian at the end of
>>> decembre, I only suggest we use :ts:issue:, more generic, instead on
>>> :ts:jira:
>>>
>>> I'll update my pull request accordingly.
>>>
>>> Cheers,
>>> Jean Baptiste Favre
>>>
>>> On 03/01/2017 15:07, Alan Carroll wrote:
>>>> Please take a look at doc/ext/traffic-server.py (which I would think you've done, if you did this patch). There are already :ts: roles defined (e.g. :ts:cv: for configuration variables). Something like :ts:jira:`3612` might be a good choice. I think the goal of this patch was so that normal usage of "TS-3612" would get converted to a JIRA link, which may be a step too far.
>>>>
>>>> On Tuesday, January 3, 2017 4:32 AM, Jean Baptiste Favre <we...@jbfavre.org> wrote:
>>>>
>>>>
>>>> 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
>>>
>
>
>
>
Re: ATS doesn't build with python docutils 0.13.1
Posted by Alan Carroll <so...@yahoo-inc.com.INVALID>.
Jack, can you put up a pull request? I'm internally debating whether we want the auto TS-XXXX linkage or not, so I think it would be good to have a PR on which to discuss it. Thanks.
On Friday, January 6, 2017 10:39 AM, Jack Bates <6n...@nottheoilrig.com> wrote:
Thanks for fixing this Jean Baptiste!
I'd like to maintain the custom autolinker,
would you mind if I restored that code and applied the fix below?
After this fix, it works with Docutils 1.3 and 1.2.
I realize it would've been much better if I'd had this ready at the
beginning of the week ...
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -166,9 +166,11 @@ pygments_style = 'sphinx'
nitpicky=1
# Autolink issue references
+# See Customizing the Parser in the docutils.parsers.rst module.
from docutils import nodes
from docutils.parsers.rst import states
+from docutils.utils import punctuation_chars
from docutils.utils import unescape
# Customize parser.inliner in the only way that Sphinx supports.
@@ -180,9 +182,34 @@ from docutils.utils import unescape
BaseInliner = states.Inliner
class Inliner(BaseInliner):
+ if hasattr(states.Inliner, 'init_customizations'):
+ def init_customizations(self, settings):
+ self.__class__ = BaseInliner
+ BaseInliner.init_customizations(self, settings)
+ self.__class__ = Inliner
+
+ # Copied from states.Inliner.init_customizations().
+ if settings.character_level_inline_markup:
+ self.start_string_prefix = u'(^|(?<!\x00))'
+ self.end_string_suffix = u''
+ else:
+ self.start_string_prefix = (u'(^|(?<=\\s|[%s%s]))' %
+ (punctuation_chars.openers,
+ punctuation_chars.delimiters))
+ self.end_string_suffix = (u'($|(?=\\s|[\x00%s%s%s]))' %
+ (punctuation_chars.closing_delimiters,
+ punctuation_chars.delimiters,
+ punctuation_chars.closers))
+
+ self.init()
+ else:
def __init__(self):
BaseInliner.__init__(self)
+ self.init()
+ # Called from __init__() in Docutils < 1.3, otherwise from
+ # init_customizations(), which was added in Docutils 1.3.
+ def init(self):
issue_pattern = re.compile(u'''
{start_string_prefix}
TS-\d+
On 04/01/17 08:08 AM, Jean Baptiste Favre wrote:
> Hello,
> I've updated my PR on github.
> We can now manage both Jira issues with ":ts:jira:`XXXX`" syntax, as
> well as github issues with ":ts:github:`XXXX`" syntax.
>
> Now, Trafficserver build succeed with doctuils 0.13.1.
> Please note that I did not test yet build against docutils 0.12.
> I'll in the coming days (docutils 0.12 is in Debian stable only).
>
> Cheers,
> Jean Baptiste
>
>
> On 03/01/2017 15:11, Jean Baptiste Favre wrote:
>> Hello Alan,
>> Thanks for the info.
>> I had a look in traffic_server.py, but to quick to notice about :ts:cv: :-/
>>
>> given the Jira to Github transition announced by Brian at the end of
>> decembre, I only suggest we use :ts:issue:, more generic, instead on
>> :ts:jira:
>>
>> I'll update my pull request accordingly.
>>
>> Cheers,
>> Jean Baptiste Favre
>>
>> On 03/01/2017 15:07, Alan Carroll wrote:
>>> Please take a look at doc/ext/traffic-server.py (which I would think you've done, if you did this patch). There are already :ts: roles defined (e.g. :ts:cv: for configuration variables). Something like :ts:jira:`3612` might be a good choice. I think the goal of this patch was so that normal usage of "TS-3612" would get converted to a JIRA link, which may be a step too far.
>>>
>>> On Tuesday, January 3, 2017 4:32 AM, Jean Baptiste Favre <we...@jbfavre.org> wrote:
>>>
>>>
>>> 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
>>
Re: ATS doesn't build with python docutils 0.13.1
Posted by Jack Bates <6n...@nottheoilrig.com>.
Thanks for fixing this Jean Baptiste!
I'd like to maintain the custom autolinker,
would you mind if I restored that code and applied the fix below?
After this fix, it works with Docutils 1.3 and 1.2.
I realize it would've been much better if I'd had this ready at the
beginning of the week ...
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -166,9 +166,11 @@ pygments_style = 'sphinx'
nitpicky=1
# Autolink issue references
+# See Customizing the Parser in the docutils.parsers.rst module.
from docutils import nodes
from docutils.parsers.rst import states
+from docutils.utils import punctuation_chars
from docutils.utils import unescape
# Customize parser.inliner in the only way that Sphinx supports.
@@ -180,9 +182,34 @@ from docutils.utils import unescape
BaseInliner = states.Inliner
class Inliner(BaseInliner):
+ if hasattr(states.Inliner, 'init_customizations'):
+ def init_customizations(self, settings):
+ self.__class__ = BaseInliner
+ BaseInliner.init_customizations(self, settings)
+ self.__class__ = Inliner
+
+ # Copied from states.Inliner.init_customizations().
+ if settings.character_level_inline_markup:
+ self.start_string_prefix = u'(^|(?<!\x00))'
+ self.end_string_suffix = u''
+ else:
+ self.start_string_prefix = (u'(^|(?<=\\s|[%s%s]))' %
+ (punctuation_chars.openers,
+ punctuation_chars.delimiters))
+ self.end_string_suffix = (u'($|(?=\\s|[\x00%s%s%s]))' %
+ (punctuation_chars.closing_delimiters,
+ punctuation_chars.delimiters,
+ punctuation_chars.closers))
+
+ self.init()
+ else:
def __init__(self):
BaseInliner.__init__(self)
+ self.init()
+ # Called from __init__() in Docutils < 1.3, otherwise from
+ # init_customizations(), which was added in Docutils 1.3.
+ def init(self):
issue_pattern = re.compile(u'''
{start_string_prefix}
TS-\d+
On 04/01/17 08:08 AM, Jean Baptiste Favre wrote:
> Hello,
> I've updated my PR on github.
> We can now manage both Jira issues with ":ts:jira:`XXXX`" syntax, as
> well as github issues with ":ts:github:`XXXX`" syntax.
>
> Now, Trafficserver build succeed with doctuils 0.13.1.
> Please note that I did not test yet build against docutils 0.12.
> I'll in the coming days (docutils 0.12 is in Debian stable only).
>
> Cheers,
> Jean Baptiste
>
>
> On 03/01/2017 15:11, Jean Baptiste Favre wrote:
>> Hello Alan,
>> Thanks for the info.
>> I had a look in traffic_server.py, but to quick to notice about :ts:cv: :-/
>>
>> given the Jira to Github transition announced by Brian at the end of
>> decembre, I only suggest we use :ts:issue:, more generic, instead on
>> :ts:jira:
>>
>> I'll update my pull request accordingly.
>>
>> Cheers,
>> Jean Baptiste Favre
>>
>> On 03/01/2017 15:07, Alan Carroll wrote:
>>> Please take a look at doc/ext/traffic-server.py (which I would think you've done, if you did this patch). There are already :ts: roles defined (e.g. :ts:cv: for configuration variables). Something like :ts:jira:`3612` might be a good choice. I think the goal of this patch was so that normal usage of "TS-3612" would get converted to a JIRA link, which may be a step too far.
>>>
>>> On Tuesday, January 3, 2017 4:32 AM, Jean Baptiste Favre <we...@jbfavre.org> wrote:
>>>
>>>
>>> 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
>>
Re: ATS doesn't build with python docutils 0.13.1
Posted by Jean Baptiste Favre <we...@jbfavre.org>.
Hello,
I've updated my PR on github.
We can now manage both Jira issues with ":ts:jira:`XXXX`" syntax, as
well as github issues with ":ts:github:`XXXX`" syntax.
Now, Trafficserver build succeed with doctuils 0.13.1.
Please note that I did not test yet build against docutils 0.12.
I'll in the coming days (docutils 0.12 is in Debian stable only).
Cheers,
Jean Baptiste
On 03/01/2017 15:11, Jean Baptiste Favre wrote:
> Hello Alan,
> Thanks for the info.
> I had a look in traffic_server.py, but to quick to notice about :ts:cv: :-/
>
> given the Jira to Github transition announced by Brian at the end of
> decembre, I only suggest we use :ts:issue:, more generic, instead on
> :ts:jira:
>
> I'll update my pull request accordingly.
>
> Cheers,
> Jean Baptiste Favre
>
> On 03/01/2017 15:07, Alan Carroll wrote:
>> Please take a look at doc/ext/traffic-server.py (which I would think you've done, if you did this patch). There are already :ts: roles defined (e.g. :ts:cv: for configuration variables). Something like :ts:jira:`3612` might be a good choice. I think the goal of this patch was so that normal usage of "TS-3612" would get converted to a JIRA link, which may be a step too far.
>>
>> On Tuesday, January 3, 2017 4:32 AM, Jean Baptiste Favre <we...@jbfavre.org> wrote:
>>
>>
>> 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
>
Re: ATS doesn't build with python docutils 0.13.1
Posted by Jean Baptiste Favre <we...@jbfavre.org>.
Hello Alan,
Thanks for the info.
I had a look in traffic_server.py, but to quick to notice about :ts:cv: :-/
given the Jira to Github transition announced by Brian at the end of
decembre, I only suggest we use :ts:issue:, more generic, instead on
:ts:jira:
I'll update my pull request accordingly.
Cheers,
Jean Baptiste Favre
On 03/01/2017 15:07, Alan Carroll wrote:
> Please take a look at doc/ext/traffic-server.py (which I would think you've done, if you did this patch). There are already :ts: roles defined (e.g. :ts:cv: for configuration variables). Something like :ts:jira:`3612` might be a good choice. I think the goal of this patch was so that normal usage of "TS-3612" would get converted to a JIRA link, which may be a step too far.
>
> On Tuesday, January 3, 2017 4:32 AM, Jean Baptiste Favre <we...@jbfavre.org> wrote:
>
>
> 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
Re: ATS doesn't build with python docutils 0.13.1
Posted by Alan Carroll <so...@yahoo-inc.com.INVALID>.
Please take a look at doc/ext/traffic-server.py (which I would think you've done, if you did this patch). There are already :ts: roles defined (e.g. :ts:cv: for configuration variables). Something like :ts:jira:`3612` might be a good choice. I think the goal of this patch was so that normal usage of "TS-3612" would get converted to a JIRA link, which may be a step too far.
On Tuesday, January 3, 2017 4:32 AM, Jean Baptiste Favre <we...@jbfavre.org> wrote:
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 <we...@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