On Saturday, April 19, 2014 6:49:45 PM UTC-5, Wes Turner wrote: > > 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? > > Issue: https://bitbucket.org/birkenfeld/sphinx/issue/1456/apidoc-add-a-m-option-to-put-module
Pull Request: https://bitbucket.org/birkenfeld/sphinx/pull-request/236/1456-apidoc-add-a-m-option-to-put-module/diff > > > 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] >> > <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. >> >> On Saturday, April 19, 2014 6:49:45 PM UTC-5, Wes Turner wrote: > > 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] >> > <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/d/optout.
