HappyDoc / Discussion / Open Discussion: Bizzare directory behavior, bad index.html?

Robert Wentworth - 2002-11-05

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?

If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
- 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.
  
  If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
- Robert Wentworth - 2002-11-06
  
  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?
  
  If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
  - 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?
    
    If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
- Robert Wentworth - 2002-11-06
  
  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?
  
  If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
- Robert Wentworth - 2002-11-06
  
  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?
  
  If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
  - 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.
    
    If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
- Robert Wentworth - 2002-11-06
  
  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)?
  
  If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
  - 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.
    
    If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Bizzare directory behavior, bad index.html?

Forums

Help

Bizzare directory behavior, bad index.html?

Bizzare directory behavior, bad index.html?

Forums

Help

Bizzare directory behavior, bad index.html? document.SUBSCRIPTION_OPTIONS = { "thing": "topic", "subscribed": false, "url": "subscribe", "icon": { "css": "fa fa-envelope-o" } };

Bizzare directory behavior, bad index.html?