#47 Root for external URL

v3.1
open
Edward Loper
5
2007-02-06
2007-01-16
Luc J. Bourhis
No

It would be nice to be able to specify in the configuration file a root for the external URL's. The need comes from documenting a Python project relying on Boost.Python bindings of C++ classes. The latter are documented with doxygen and I would like to link to those HTML pages from the documentation of the Python side which I create with epydoc. But then I am at the moment forced to hardwire the server address into the URL's and that's not nice.

Luc Bourhis

Discussion

  • Logged In: YES
    user_id=1053920
    Originator: NO

    What about adding a configuration option with a placeholder, such

    external_url = "http://path/to/other/docs/%s.html"

    and use Docutils interpreted text to refer to it, such :ext:`MyClass`.

    mmm... so there would be a single target. Maybe it would be useful to add new interpreted text rules on the fly, given a list of configured patterns. Example:

    external_url = "foo=http://path/to/other/docs/%s.html"
    external_url = "bar=http://path/to/other/docs/%s-Class.html"

    class Baz:
    """
    This class wraps the C class :foo:`FooBaz`. It uses the
    external class :bar:`Frobble` to do the hard work.
    """

     
    • milestone: --> v3.1
     
  • Logged In: NO

    The first solution with a single target would fit my current needs. But I can indeed foresee the need for more than one external URL base. Your second syntax is fine but the real problem is elsewhere. More complex templates are necessary to generate the URL's. For example, the documentation for a class scitbx::lbfgs::minimizer is put at the following URL by Doxygen
    .../classscitbx_1_1lbfgs_1_1drop__convergence__test.html
    When I say complex templates, well, obviously the easiest would be to let the user specify some hook to run his own Python URL generation.

    Please, note that at the moment, I have worked around the problem by using the syntax U{DOXYCLASS:scitbx::lbfgs::minimizer} and then postprocessing the htm files produced by epydoc to generate the Doxygen URL's

    Thanks for your interest in my problem.

     
  • Logged In: NO

    The first solution with a single target would fit my current needs. But I can indeed foresee the need for more than one external URL base. Your second syntax is fine but the real problem is elsewhere. More complex templates are necessary to generate the URL's. For example, the documentation for a class scitbx::lbfgs::minimizer is put at the following URL by Doxygen
    .../classscitbx_1_1lbfgs_1_1drop__convergence__test.html
    When I say complex templates, well, obviously the easiest would be to let the user specify some hook to run his own Python URL generation.

    Please, note that at the moment, I have worked around the problem by using the syntax U{DOXYCLASS:scitbx::lbfgs::minimizer} and then postprocessing the htm files produced by epydoc to generate the Doxygen URL's

    Thanks for your interest in my problem.

     
  • Logged In: YES
    user_id=1053920
    Originator: NO

    As you may have seen, a feature like the one you asked for has been made available for a few days in the trunk and has been deployed in epydoc 3.0 beta.

    Currently an epydoc-generated documentation can both reference other documents and provides a mapping file that can be used if somebody else wants to refer to it. Epydoc can also reference doxygen-generated documentation if a mapping file is provided; the file and the usage are described in http://epydoc.sourceforge.net/epydoc.html#external-api-links

    Would it be possible to crawl over a set of doxygen-generated html files and produce a file listing the object names (such as 'scitbx::lbfgs::minimizer') and the url to be referred ('classscitbx_1_1lbfgs_1_1drop__convergence__test.html', in your example)? It seems similar to the post-processing work you usually perform on the Epydoc output. Such index file may be used by Epydoc to generate external links; the server url is a configuration parameter.