On Jun 3, 6:02 am, Florent Hivert <[email protected]> wrote: > - 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.
Hi Florent, 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. 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. 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 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. Thank you for working on this! Andrey -- 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
