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] > <mailto:[email protected]>> 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] > <mailto:sphinx-users%[email protected]>. > To post to this group, send email to [email protected] > <mailto:[email protected]>. > 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]. > 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/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/groups/opt_out.
