Hi Andrey, > > - Should we search the link in all.py or in the local module ? In the latter > > solution we can only link what is imported in the current module, keeping > > the > > doc coherent with the module.
> I think it would be better to search all.py and then imports in the > local module. One of them is probably not sufficient, since there may > be imports that are not exposed by all.py. That is indeed the case from my experiments. > On the other hand, in the module there may be imports through all.py and as > I understand for the final documentation we need to have the exact path to > the module where things are defined. That is not a problem: even if things are imported through all.py, once I found a sage object obj, I can finds its actual module using obj.__module__. > Looking at the module alone may not be enough > because potentially docstrings may include something like "See > also ... if you need ..." to reference things which are relevant, but > are not used in the module itself. > > - I can also take the chance to raise warning for really dangling links if > > needed. Maybe this should be configurable by an environment variable, say > > SAGE_DOC_WARN_DANGLING_LINKS. > > > > That would be wonderful! I was actually surprised that it is not the > case by default, since I recently made some typos in the documentation > and caught them after going over the result, but with warnings it > would be much easier and more reliable. I can tell you that if you do that by default, there will be a really huge bunch of warning... > I think these warnings are of higher priority than "document is not included > into any toc-tree" or something like that which I had to read again and > again if I was popping out some of the queue patches to work on the middle > ones. Yes ! I don't know how but I would be very happy to have a way to get rid of those without having to nuke doc/output and rebuild the whole doc. Note That I don't know either how to have warning with a higher priority. The good news it that the "document is not included into any toc-tree" occur during the "checking consistency..." phase whereas "dangling links" will occur during the "writing output..." phase. So they won't mix up. Florent -- To post to this group, send an email to [email protected] To unsubscribe from this group, send an email to [email protected] For more options, visit this group at http://groups.google.com/group/sage-devel URL: http://www.sagemath.org
