How to programmatically add "orphan" flag?

[Matthias Geier]

Dear list.

Given a docutils "document" object (e.g. the output of the RST
parser), how can I add the "orphan" flag to its field list?

Previously, I've worked around this question by manipulating the
Environment like this:

env.metadata['mydocname']['orphan'] = ''

However, this doesn't seem to work with Sphinx 1.4.9 and 1.5.1 and
1.5.3 and 1.5.6 and probably other versions.

cheers,
Matthias

[Komiya Takeshi]

Hi Matthias,

Hmm, your code seems good. What event did you modify metadata?
Sphinx refers it on consistency-checking phase. So it should be
changed on reading phase.

BTW, I think new API is needed to add metadata. To modify internal
data directly is a bit ugly and fragile.

Thanks,
Takeshi KOMIYA

> --
> 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.

[Matthias Geier]

Hi Takeshi, thanks for the quick answer!

On Wed, Jan 17, 2018 at 3:15 AM, Komiya Takeshi wrote:
> Hi Matthias,
>
> Hmm, your code seems good. What event did you modify metadata?
> Sphinx refers it on consistency-checking phase. So it should be
> changed on reading phase.

I guess I modified it too early, I was trying to do it while I was
still parsing the source file.
It's there: https://github.com/spatialaudio/nbsphinx/blob/91c4eae1ce7b2fd23117302913ca2f5e6e5167b3/src/nbsphinx.py#L686

I'm really not surprised that this doesn't work, I was rather
surprised that it *did* work in several Sphinx versions, including the
current one.

But I just found a much better way than manipulating the document
nodes manually: I'm just using the RST parser!

Before parsing my actual source file, I'm just doing something like this:

rstparser.parse(':orphan:', document)

And that does the trick!

That's the change if you are interested:
https://github.com/spatialaudio/nbsphinx/commit/1a2001c9b5a49816af4660d831bc99ab10147324

> BTW, I think new API is needed to add metadata. To modify internal
> data directly is a bit ugly and fragile.

Yeah, I guess it is. But I don't know how many people really need this.
I don't need it anymore since I found a simpler way.

cheers,
Matthias

[Komiya Takeshi]

>I'm really not surprised that this doesn't work, I was rather
>surprised that it *did* work in several Sphinx versions, including the
>current one.

Before Sphinx-1.6, the metadata is initialized at beginning of
collection metadata.
Then metadata written in parser is ignored.

On the other hand, since 1.6, the metadata is initialized at
instantiation of Application using defaultdict.
As a result, the metadata is merged with doctree's.

>Yeah, I guess it is. But I don't know how many people really need this.
>I don't need it anymore since I found a simpler way.

Okay, let's discuss again if anybody will need it :-)

Thanks,
Takeshi KOMIYA