Bizzare directory behavior, bad index.html?

2002-11-05
2002-11-06
  • There must be something I don't understand about how to use HappyDoc, because directory related behavior is bizarre and index.html files for parent packages contain no useful information.

    Given a Unix command line as follows:

          happydoc -T SingleFile --no-private-names --no-comments -title "Foo Framework" /home/rwentwor/jytest/jythonlib

    where the source files are in /home/rwentwor/jytest/jythonlib/jyfulfill/support/util and there are __init__.py files in /home/rwentwor/jytest/jythonlib/jyfulfill/ and subdirectories thereof...

    I get a doc directory containing:

    home

    home/index.htm

    home/rwentwor

    home/rwentwor/jytest

    home/rwentwor/jytest/jythonlib

    home/rwentwor/jytest/jythonlib/jyfulfill

    home/rwentwor/jytest/jythonlib/jyfulfill/home

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/index.html

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home/rwentwor

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home/rwentwor/jytest

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home/rwentwor/jytest/jyfulfill

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home/rwentwor/jytest/jyfulfill/support

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home/rwentwor/jytest/jyfulfill/support/util

    home/rwentwor/jytest/jythonlib/jyfulfill/home/rwentwor/jytest/jythonlib/jyfulfill/support/home/rwentwor/jytest/jyfulfill/support/util/index.html

    Note that: the directory structure is recursively nested three times. There are index.html files in only a few places. Except for the last index.html file (which contains documentation from my source files) the other index.html files are useless: they contain no listing of sub-packages or hyperlinks to anything but themselves.

    Suggestions?

     
    • Doug Hellmann
      Doug Hellmann
      2002-11-05

      No, this is a bug.  You are using it properly.

      Try these commands instead:

      % cd /home/rwentwor/jytest
      % happydoc -T SingleFile --no-private-names --no-comments -title "Foo Framework" jythonlib

      That should give you a doc directory with everything under jythonlib documented inside.

       
    • Thanks, that fixes the bizarre recursive directory structure.

      But it doesn't solve my problem with index.html. The display of doc/jythonlib/jyfulfill/index.html looks something like the following:

      -------------------------------

      Table of contents

      itle: jyfulfill
                         No package level documentation

      Module: __init__
                         Docstring from __init__ module

                         Imported modules
                                         import os
                                         import sys

      Table of Contents

      -------------------------------

      There are a number of problems with this:

      1) Most seriously, jyfulfill contains several subpackages, but these are not mentioned, nor is there any link to their documentation.

      2) The two "Table of Contents" links link back to this same page -- they go nowhere and seem to serve little function.

      3) What should presumably be "Title: jyfulfill" instead is truncated to "itle: jyfulfill".

      Is there some way to coerce better behavior with respect to these issues?

       
      • Doug Hellmann
        Doug Hellmann
        2002-11-06

        So the index.html file doesn't actually contain HTML?  I wonder if the SingleFile docset is broken.  I don't use that one very often.  Does it work if you don't specify that option?

         
    • Thanks, that fixes the bizarre recursive directory structure.

      But it doesn't solve my problem with index.html. The display of doc/jythonlib/jyfulfill/index.html looks something like the following:

      -------------------------------

      Table of contents

      itle: jyfulfill
                         No package level documentation

      Module: __init__
                         Docstring from __init__ module

                         Imported modules
                                         import os
                                         import sys

      Table of Contents

      -------------------------------

      There are a number of problems with this:

      1) Most seriously, jyfulfill contains several subpackages, but these are not mentioned, nor is there any link to their documentation.

      2) The two "Table of Contents" links link back to this same page -- they go nowhere and seem to serve little function.

      3) What should presumably be "Title: jyfulfill" instead is truncated to "itle: jyfulfill".

      Is there some way to coerce better behavior with respect to these issues?

       
    • Yes, index.html contains HTML.  That's not the problem.  My main question is: how do I make it so that index.html for a package includes links to the documentation for sub-packages?

       
      • Doug Hellmann
        Doug Hellmann
        2002-11-06

        Ok, I misunderstood what you were saying.

        The index.html file should just include those references.  Try the default docset.  If that works (generating multiple index.html files that are cross-linked) then the problem is in the SingleFile docset.  If it does not work, then something else is going on.

         
    • Ok, yes, with the default docset those subpackages do show up.

      I also managed to clear up the problem with titles being "itle: packagename".  The problem was I was using "-title" as an option instead of "-t".

      Remaining minor oddities:

      1) The package level documentation contains the complete documentation from __init__.py, and also include a link (in the modules and packages section) to another page that also includes all the documentation from __init__.py.

      2) All pages include "Table of Contents" links. For module documentation pages, these links take one back to the root page of the documentation tree.  But for package documentation pages, these links link back to the current page, taking you nowhere."

      While it might be nice to have ways of dealing with these quirks, the system is usable at this point.  Is there any way of addressing (1) and/or (2)?

       
      • Doug Hellmann
        Doug Hellmann
        2002-11-06

        Ok, good, so at least you're able to generate something useful even if it isn't in the format you want.

        The remaining oddities:

        1. This is by design.  At least, the __init__.py module is not specifically excluded from the list of modules.  I think I've had this behavior mentioned as odd before, but no one took the time to write up a feature request and it doesn't bother me, so I haven't done anything about it.

        2. This is a bug, and it would be helpful if you would submit it to the bug tracker so I don't forget to look into the problem.