Re: Override one of the default builders

[Robert Lehmann]

[sphinx-dev to bcc]

Hi Viktor,

This mailing list (sphinx-dev) is for the development of Sphinx, not so much for using/extending it.  sphinx-users@ is the higher-traffic list where you have much higher chances of somebody from outside the core team replying.

Looking at the blame view for application.py, it seems sphinx.Sphinx just recently (9d ago) grew the registry attribute.  Why do you have to override the default builder in the first place?  Why not just add a new one? :-)

Hope this helps,

Robert

On Tue, Apr 25, 2017 at 7:28 PM, Viktor Haag <vikto...@gmail.com> wrote:

Starting to look at updating to the upcoming Sphinx v1.6, and I have a question about using a custom builder.

We have a builder that is, effectively, a simple wrapper around the basic HTML builder. It would be nice to have the ability to provide this custom builder as an override to the built-in HTML builder. Is there a way in 1.6 to allow one to overload a built-in builder?

I can do this:

class MyBuilder(StandaloneHtmlBuilder):

name = 'mybuilder'

## the stuff I'm overriding on the standalone html builder 

 

def setup(app):

app.add_builder(MyBuilder)

But I thought I could have done something like this, but  Sphinx complains that the app 'Sphinx' has no registry attribute (which seems odd to me):

class MyBuilder(StandaloneHtmlBuilder):

name = 'html' 

## the stuff I'm overriding on the standalone html builder

 

def setup(app):

app.registry.builder['html'] = MyBuilder

Is there a reasonable way to override a built-in builder that re-uses the builder name, but uses the inheriting local class as the builder class? (The reason I'd like to re-use the builder name is that the Makefile support for sphinx understands the default builder names and makes decisions about where to put the output directory and so on, based on the builder name.)

--

Viktor Haag

--
You received this message because you are subscribed to the Google Groups "sphinx-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-dev+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Komiya Takeshi]

Hi Viktor,

there are no way to override built-in builder. We just provide the way
to add new one.
In the first case you shown, you can build HTML with `sphinx-build -b
mybuilder ...` command.
How about rewriting your Makefile?

Thanks,
Takeshi KOMIYA

> email to sphinx-dev+...@googlegroups.com.

[Viktor Haag]

Hi Robert.

Thanks for the advice about groups -- I apologize for not realizing that extension questions should actually go into sphinx-users.

To answer your question about why do I want to override a default builder; really, for two reasons:

- Because I want _nearly_ all the functionality in the HTML builder, but I want to make one tiny change, because of the way our local docs source works.

 

- Because we don't ever really want to build HTML stuff that does not use this tiny change, and our workflow scripts that do publishing of our docs know where the output for a build actually goes (into an "html" directory -- they would have to change if we had a different builder name; not a big change at all, but still, a change in the overall workflow).

It turns out that I do have access to the app's registry; it was my build environment that was using an older version of Sphinx despite the fact that I thought I had the newer one in the documentation chain's load path.

It turns out, if I just do this, it works (I understand that it's not exactly wanting to be supported this way; it's hackery):

class MyHtmlBuilder(StandaloneHtmlBuilder):

   name = 'html'

   # override get_doc_context

   def get_doc_context(self, docname, body, metatags):

       # local adjustments to the doc context for our own purposes

def setup(app):

   app.registry.builders['html'] = MyHtmlBuilder 

[Viktor Haag]

On Tuesday, 2 May 2017 21:52:22 UTC-4, Komiya Takeshi wrote:

Hi Viktor,

there are no way to override built-in builder. We just provide the way
to add new one.
In the first case you shown, you can build HTML with `sphinx-build -b
mybuilder ...` command.
How about rewriting your Makefile?

Thanks,
Takeshi KOMIYA

Hi!

Yes, I know that I can make my own builder, and then just add it through the supported API and build using that. The only disadvantage there is that the output directories get named after the builder name, and we have a host of people (and scripts) that now are conditioned/written to use "make html" and to look for the output in a 'html' directory.

It's a small thing to change that, actually, and it would be more supportable, but I was still hoping to be able to name a builder 'html' (or, to be able to specify the name of the output directory for the docs instead of the builder-name being used as the output directory name).

--

V. 

[Komiya Takeshi]

Hi,

I don't have strong opinion for your idea. So I can accept to add a
new API for overriding built-in builders if other maintainers don't
opposite. But, at this moment, we're going to release Sphinx-1.6 now.
So it will be included in Sphinx-1.7 or later.

>(or, to be able to specify the name of the output directory for the docs instead of the builder-name being used as the output directory name).

Sphinx does not prevent that. sphinx-build command takes output
directory as an argument. So please rewrite your Makefile as you like.

Note: app.registry is a kind of internal module. so we don't promise
you the interface of the module. So I don't recommend you to use it.

Thanks,
Takeshi KOMIYA