For many cases, I think it makes sense to read the module documentation before the submodule documentation.
I think this would be an excellent feature to have as a configurable option. In terms of reading through the source, the traversal is: module -> submodule -> submodule The output format would be similar. @Luc Do you have a patch for this or would you mind if I implemented this as a commandline option? On Sunday, February 9, 2014 10:32:19 PM UTC-6, Luc Saffre wrote: > > Yes, de gustibus non est disputandum, but since it seems not trivial to > make this choice configurable, we might analyze a bit deeper and try to > find out *why* our preferences differ. If we get to some consensus, this > would add knowledge to Sphinx. My two cents to this discussion are then: > I think "my" way is better in packages with lots of subpackages. For > example (I didn't verify but I guess that) the documentation for > Python's xml package had to be done manually because current apidoc > output simply would not be readable: > http://docs.python.org/3/library/xml.html > > Luc > > On 10/01/14 18:32, Kevin Horn wrote: > > I have to say that I prefer it the way it is, rather than the way you've > > done it. > > > > I also can't imagine why you like your way better, but I guess that's > > why we're different people. :) > > > > I might be nice to have it configurable though, if it doesn't introduce > > too much complexity into the code. > > > > > > On Fri, Jan 10, 2014 at 6:15 AM, Luc Saffre > > <[email protected]<javascript:> > > <mailto:[email protected] <javascript:>>> wrote: > > > > Hi all, > > > > I made a little change to apidoc.py which I'd like to share here. I > > didn't like the fact that apidoc generates, in the main module of a > > package, first the sections "Submodules" and "Subpackages" and only > then > > the "Module contents". I prefer to have the module contents (without > > section header) at the beginning of the file, followed only then by > the > > packages. > > > > In file apidoc.py, lines 91ff, function create_package_file, I moved > the > > following two lines towards the beginning (just after the ``text = > > format_heading(1, '%s package' ...`` line:: > > > > # text += format_heading(2, 'Module contents') > > text += format_directive(subroot, master_package) > > > > and after these lines I insert another blank line to the output:: > > > > text += '\n\n' > > > > Here is an example output generated using these changes: > > http://lino-framework.org/api/lino.utils.html > > > > For me this way is much better. I don't imagine how somebody might > > prefer it the other way. But since this part of the apidoc output > cannot > > easily be made configurable, we need to discuss here whether this > new > > format might be acceptable for everybody. I must say that I use the > > `--separate` option, and that I don't claim to have made very deep > > investigations. > > > > What do other people think about this? > > > > Luc > > > > -- > > You received this message because you are subscribed to the Google > > Groups "sphinx-users" group. > > To unsubscribe from this group and stop receiving emails from it, > > send an email to [email protected] <javascript:> > > <mailto:sphinx-users%[email protected] <javascript:>>. > > To post to this group, send email to > > [email protected]<javascript:> > > <mailto:[email protected] <javascript:>>. > > Visit this group at http://groups.google.com/group/sphinx-users. > > For more options, visit https://groups.google.com/groups/opt_out. > > > > > > > > > > -- > > -- > > Kevin Horn > > > > -- > > You received this message because you are subscribed to the Google > > Groups "sphinx-users" group. > > To unsubscribe from this group and stop receiving emails from it, send > > an email to [email protected] <javascript:>. > > To post to this group, send email to > > [email protected]<javascript:>. > > > Visit this group at http://groups.google.com/group/sphinx-users. > > For more options, visit https://groups.google.com/groups/opt_out. > > -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at http://groups.google.com/group/sphinx-users. For more options, visit https://groups.google.com/d/optout.
