Discussion:
Override one of the default builders
(too old to reply)
Viktor Haag
2017-04-25 17:28:19 UTC
Permalink
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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Robert Lehmann
2017-05-02 15:13:11 UTC
Permalink
[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@
<https://groups.google.com/d/forum/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
<https://github.com/sphinx-doc/sphinx/blame/master/sphinx/application.py>,
it seems sphinx.Sphinx just recently
<https://github.com/sphinx-doc/sphinx/commit/72f267c6ae27144b46a23725b6634cc35f03fb50>
(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
Post by Viktor Haag
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?
name = 'mybuilder'
## the stuff I'm overriding on the standalone html builder
app.add_builder(MyBuilder)
But I thought I could have done something like this, but Sphinx complains
name = 'html'
## the stuff I'm overriding on the standalone html builder
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
For more options, visit https://groups.google.com/d/optout.
--
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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Viktor Haag
2017-05-08 19:24:01 UTC
Permalink
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
Post by Robert Lehmann
Looking at the blame view for application.py
<https://github.com/sphinx-doc/sphinx/blame/master/sphinx/application.py>,
it seems sphinx.Sphinx just recently
<https://github.com/sphinx-doc/sphinx/commit/72f267c6ae27144b46a23725b6634cc35f03fb50>
(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? :-)
--
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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Komiya Takeshi
2017-05-03 01:52:00 UTC
Permalink
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
Post by Viktor Haag
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?
name = 'mybuilder'
## the stuff I'm overriding on the standalone html builder
app.add_builder(MyBuilder)
But I thought I could have done something like this, but Sphinx complains
name = 'html'
## the stuff I'm overriding on the standalone html builder
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
For more options, visit https://groups.google.com/d/optout.
--
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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Viktor Haag
2017-05-08 19:26:29 UTC
Permalink
Post by Robert Lehmann
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.
--
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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Komiya Takeshi
2017-05-11 05:42:44 UTC
Permalink
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
Post by Robert Lehmann
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.
--
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
For more options, visit https://groups.google.com/d/optout.
--
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+***@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.
Loading...