include directive and relative paths are biting me

[Marc van Grootel]

Hi all,

I'm using sphinx and rst for a while now but now I am trying to build a more complex set of documentation and I find that the include directive is biting me. I was a bit surprised that this hasn't bitten me before.

I am trying to build a kind of hub where it's documentation is in one directory. I would like to pull in documentation from other project directories but I don't want to set up a separate sphinx doc set for each of these projects (there will be many small projects).

The fact that sphinx relative references will be resolved relative to the main sphinx directory looks like a serious blocker.

Example:

  [hub/index.rst]

       .. include:: ../projects/a/index.rst

  [../projects/a/index.rst]

      Hello I am project A

      .. include:: foo.py

  [../projects/a/foo.py]

      print "I am project A too"

Note that ../ can be any relative path (as rst include doesn't deal with abs paths at all)

I've googled a bit and found what I thought might offer a solution in a blog post by Reinout van Rees

http://reinout.vanrees.org/weblog/2010/12/08/include-external-in-sphinx.html

This seems to work but not really. Whenever the rst from the external project also uses an include then this still works with the original, hub directory as base directory.

I've looked at intersphinx but this mechanism seems to be aimed at linking and not including/embedding.

See for example https://bitbucket.org/birkenfeld/sphinx/issue/1204/relative-target-path-for-intersphinx-leads

Compare this to how includes usually work in XML tools. Whenever I resolve relative paths in XSLT they resolve relative to the xml:base URI of the document that contains the link. Even when embedding. This behaviour seems natural to me and from the XML perspective the rst include semantics feel wrong to me.

So I guess I have two questions now.

a) is there a way to get what I need without needing to deal with symlinks (... windows, you know, don't ask ;-)

b) wouldn't it be better to use the latter semantics (or maybe there's a need for a new directive .. xinclude:: that uses it?)

... or maybe someone can explain what the rationale is to have the current semantics as I fail to see it (apart maybe from a security standpoint)

The only solution I can see now is to introduce an extra build step which gathers all documentation and copies it under the hub directory.

I hope I've explained myself well enough.

Thanks,

--Marc

[gilberto dos santos alves]

hi!

if you have root access you could see all real path and (logical or symbolic link path).

Many admin creates a structure of path using command ( ln -s ....). Many times this use make things more easy but more complex to manage. This is more related to environment infrastructure.

Yes windows also have (logical or symbolic link path).

This things occurs using http server, python django apps, css styles, javascripts and type of include that we use spread on web.

"a) is there a way to get what I need without needing to deal with symlinks (... windows, you know, don't ask ;-)"

IMHO use symbolic links give us great flexibility, this is main reason of wide use.

Please post more details about your environment and we could help you.

regards

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

--
gilberto dos santos alves
+55.11.98646-5049
sao paulo - sp - brasil

[Marc van Grootel]

Hi Gilberto,

Thanks but no. I don't think that I want to go with any form of symbolic links for what I want to achieve. Contrary to what you say I haven't had much success making such an approach work consistently across Windows/Mac/Unix. Mostly due to Windows. They are hard to maintain and do not work with all tools.

The longer I think about the issue the more I think the semantics that rst uses for include is wrong. But I think I am going to work around it and maybe "mount" such an external projects using a field and if necessary take the leap to extend rst/sphinx. In the end the rst XML is more important to me than the HTML rendering and I think I can get there using this approach.

Thanks

--Marc

[Marc van Grootel]

... or thinking a bit more

Maybe intersphinx after all, and using links rather than embedding is the way to go. I can always use embedding semantics when following such links while processing the rst XML.

I think I got it ;-)

--Marc

[gilberto dos santos alves]

yes. symbolic link is very powerfull and on http / ftp may could a trap. regards.

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