Proposal: Making Writers easier to patch

[Volker Jaenisch]

Hi Sphinx People!

Patching a Sphinx Writer by overloding a visit-*-method is possible. But it is not really usefull. This is because the visit-*-methods are directly changing local state.

So any overloding will be a code copy.

A simple solution may be to seperate the calculation of the state from setting it.

e.g. lets transfrom

    def visit_desc_parameter(self, node: Element) -> None:
        if self.first_param:
            self.first_param = 0
        elif not self.required_params_left:
            self.body.append(self.param_separator)
        if self.optional_param_level == 0:
            self.required_params_left -= 1
        if not node.hasattr('noemph'):
            self.body.append('<em class="sig-param">')

into something like

    def visit_desc_parameter(self, node: Element) -> None:

        appends, params = self.visit_desc_parameter_values(node)

        for append in appends:

          self.body.append(append)

        for param, value in params.items:

          self[param] = value

  def visit_desc_parameter_values(self)

       appends = []

       params = {}

        if self.first_param:
            params['first_param'] = 0
        elif not self.required_params_left:
            appends.apend(self.param_separator)
        if self.optional_param_level == 0:
            params['required_params_left'] -= 1
        if not node.hasattr('noemph'):
            appends.append('<em class="sig-param">')

        return (appends, params)

With this change visit_desc_parameter_values could be easily overwritten.

 

I volunteer to make a pull request.

Cheers,

Volker