Hi Mike, I'm still trying to improve my sphinx expertise :-)
> > I'd like to have some crossref back and forth from sage source __doc__ to > > some > > rst file under doc/en/... and as well to some html files provided by some > > spkg. This raise two different but related questions: > > > > 1 - It seems that Sphinx build environment when building the reference > > manual > > and construction for example are unrelated. I can't manage to have link > > working back and forth. For example, I can't manage to have the link > > :mod:`sage.combinat.permutation` to work in constructions/groups.rst or to > > have :ref:`_chapter-groups` to work from sage/combinat/permutations.py > > The way to handle linking across different documents is the > intersphinx extension: > http://sphinx.pocoo.org/latest/ext/intersphinx.html , but there may be > some issue with locally browseable docs and docs that are online if > their file layouts are different. I got intersphinx working to resolve links to Python reference manual. This resolve automatically a *lot* of dangling links in the doc including those automatically generated when the base class of a class is a builtin Python class that is most of the time object (eg sage.combinat.backtrack.GenericBacktracker). Since we probably don't want sage to access to the internet when compiling the do (do we ?) I manually downloaded the crossref database from Python site at http://docs.python.org/objects.inv and put the link at the right place in conf.py. For those who wonders this database is 369785 bytes so I think there is no problem to include it in sage. A few questions / requests for a vote: - do we want this feature ? - do you think it is the right way to go or is it Ok to let sage access to Python site when compiling ? - if Python update their doc, they is some risks that some of our links become wrong. We probably only link to very stable Python stuff so this risk should be very low. Still if the database is hardcoded in Sage, it could be a good idea to update it every release. How to handle that ? Now to go to more advanced stuff, I'd like to be able to link back an forth .rst files and python module. It seems that sphinx handles them differently since the objects.inv name generated when compiling construction is empty. Right now I don't know how to solve this problem so that any help is welcome... Anyway, reading sphinx-devel I have the impression that those things are improved in the upcomming 1.0 release. So we probably want to wait for it before dealing with more involved stuff. I'm putting my patch on #9128. Please comment. > > 2 - Suppose that we want to provide an spkg with some included html doc, > > say > > some Python doc in html. So the doc would be stored somewhere under > > $SAGE_ROOT > > say starting from $SAGE_ROOT/local/doc/python/index.html what would be the > > good way to link it from within sage doc (both .py and .rst files) ? > > I believe intersphinx can fail gracefully if those don't links don't > exist. If you're talking about automatically putting links to that in > the main documentation index, then we could make a Sphinx directive to > detect those and include them if their locations were standardized. That's a good idea... Cheers, Florent -- To post to this group, send an email to sage-devel@googlegroups.com To unsubscribe from this group, send an email to sage-devel+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
