Force the order to read the documents

[Guillem Barba Domingo]

Hello,

I'm developing the inheritance extension [1][2] which allows that a document modify the content of another one.

After an exhausting fight with the sphinx internals ;-) I get to generate correctly the final document with all ToC and toctree.

But to do it I had to modify the sphinx core to force an specific order to read the documents. You can view the change in this commit [3] (I pushed it only to make it public, of course, it isn't a real proposition of change).

I tried to get it without modify sphinx core but I couldn't, because if I apply the inheritances on 'toctree-resolved' event action (to ensure that all docs has been read before => all inheritances are in 'inherits' dictionary) the toctrees are not generated correctly.

If I don't force the order to read the documents, not all inheritances are applied (because the document that extend is read after the document inherited).

In my case (this extension is to generate the manual for Tryton ERP dynamically) the order os inheritance_moduels is generated, in conf.py, by the dependency graph algorism of Tryton.

SO, if I prepare a patch to add a mechanism to be able to force an order in the loop of update().update_generator() method of environment it will be accepted?

I'm not sure how it should be to be extensible in an extension. Any directions or an extension that hack environment methods are welcome.

And if someone has any alternative idea about how to solve my problem, they are also very welcome

PD: as the release version show, it is under development. Please, note me if you are using it to advice about incompatible changes.

[1] https://bitbucket.org/nantic/sphinxcontrib-inheritance

[2] https://pypi.python.org/pypi/sphinxcontrib-inheritance

[3] https://bitbucket.org/guillemNaN/sphinx/commits/f3038a6015af3d2d42f7bbadca4adc91ca92efac?at=stable

--
Guillem Barba
http://www.guillem.alcarrer.net

[Takayuki Shimizukawa]

Hi Guillem,

If the patch doesn't affect to current sphinx behavior and it doesn't
introduce large complexity, I think it will be accepted.

I think introducing a new event will resolve the issue.

https://bitbucket.org/birkenfeld/sphinx/src/d2537dee/sphinx/environment.py#cl-471:

# read all new and changed files
docnames = sorted(added | changed)
if app:
docnames = app.emit('env-read-docs', self, docnames)
for docname in docnames:
yield docname
self.read_doc(docname, app=app)

The event allow extension author modify docnames list before
processing; reordering, append and remove.
I think this change is reasonable.

Regards,
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

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

[Guillem Barba Domingo]

El 30/07/2014 17:25, "Takayuki Shimizukawa" <shimi...@gmail.com> va escriure:

>
> Hi Guillem,
>
> If the patch doesn't affect to current sphinx behavior and it doesn't
> introduce large complexity, I think it will be accepted.
>
> I think introducing a new event will resolve the issue.
>
> https://bitbucket.org/birkenfeld/sphinx/src/d2537dee/sphinx/environment.py#cl-471:
>
>     # read all new and changed files
>     docnames = sorted(added | changed)
>     if app:
>         docnames = app.emit('env-read-docs', self, docnames)
>     for docname in docnames:
>         yield docname
>         self.read_doc(docname, app=app)
>
> The event allow extension author modify docnames list before
> processing; reordering, append and remove.
> I think this change is reasonable.

Pretty nice!! The event is the way, of course.
I will prepare a PR with your proposal and changes in documentation.
I hope it will be done tomorrow.

Thanks!
Guillem

[Guillem Barba Domingo]

I did the PR [1]. I did it over 'default' branch because as it is a new feature I suposed it should be in the next release.

Is there any prevision about when it will be released?

[1] https://bitbucket.org/birkenfeld/sphinx/pull-request/261/add-env-read-docs-event-to-allow-modify

[Takayuki Shimizukawa]

Hi Guillem,

Thanks for the PR!

2014-08-01 1:30 GMT+09:00 Guillem Barba Domingo <guille...@gmail.com>:
> I did the PR [1]. I did it over 'default' branch because as it is a new
> feature I suposed it should be in the next release.

Right.

> Is there any prevision about when it will be released?

I'm going to release Sphinx-1.3b1 in a month.
Can you write test cases for the PR? It makes a effort to the progress.

Thanks!

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

[Guillem Barba Domingo]

El 01/08/2014 15:52, "Takayuki Shimizukawa" <shimi...@gmail.com> va escriure:
>
> Hi Guillem,
>

> Thanks for the PR!
>
> 2014-08-01 1:30 GMT+09:00 Guillem Barba Domingo <guille...@gmail.com>:
> > I did the PR [1]. I did it over 'default' branch because as it is a new
> > feature I suposed it should be in the next release.
>
> Right.
>
> > Is there any prevision about when it will be released?
>
> I'm going to release Sphinx-1.3b1 in a month.
> Can you write test cases for the PR? It makes a effort to the progress.

I will try.
I can't found any test for an event. Do you know if there is anyone that I can take as example. If not, don't worry.

[Takayuki Shimizukawa]

Hi Guillem,

2014-08-01 23:55 GMT+09:00 Guillem Barba Domingo <guille...@gmail.com>:
>> Can you write test cases for the PR? It makes a effort to the progress.
>
> I will try.
> I can't found any test for an event. Do you know if there is anyone that I
> can take as example. If not, don't worry.

Thanks!

I think this test file is good to mimic for this case.
https://bitbucket.org/birkenfeld/sphinx/src/d2537dee/tests/test_versioning.py

Don't hesitate to ask any questions.
Thanks.

[Guillem Barba Domingo]

Thank you!

Unfortunately I think I can't do it before the release (I start a very necessary holidays next week far far away of any computer :-P), but I'm very interested that this PR was included in the next release to could publish new release of my extensions and stop to install it from repository.

You have my word I will implement the test  when I come back.