apidoc output format

[Luc Saffre]

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

[Kevin Horn]

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.

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 sphinx-users...@googlegroups.com.
To post to this group, send email to sphinx...@googlegroups.com.
Visit this group at http://groups.google.com/group/sphinx-users.
For more options, visit https://groups.google.com/groups/opt_out.

--
--

Kevin Horn

[Luc Saffre]

On 10/01/14 18:32, Kevin Horn wrote:
> I also can't imagine why you like your way better, but I guess that's
> why we're different people. :)

Another guess is that you don't use `--separate`. If this is true, then
we could say that my suggested format should be applied if and only if
`--separate` is set.

> I might be nice to have it configurable though, if it doesn't introduce
> too much complexity into the code.

If the above is okay, then I suggest to not add another command-line
option. To make apidoc more flexible in the long term I'd suggest to
consider switching to a system based on Jinja templates.

Luc

[Luc Saffre]

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:

> <mailto:sphinx-users%2Bunsu...@googlegroups.com>.

> To post to this group, send email to sphinx...@googlegroups.com

> <mailto:sphinx...@googlegroups.com>.

[Wes Turner]

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?

[Wes Turner]

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

[Luc Saffre]

On 20/04/14 03:12, Wes Turner wrote:
>
> 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
>

Great! I tried this as follows:

Made "hg pull -u" in my local copy of the repository, but (of course)
your pull request isn't yet in default branch.

$ hg pull -u https://bitbucket.org/westurner/sphinx/\
branch/apidoc_output_order
searching for changes
adding changesets
adding manifests
adding file changes
added 2 changesets with 1 changes to 1 files (+1 heads)
0 files updated, 0 files merged, 0 files removed, 0 files unresolved

$ hg update apidoc_output_order

So I can confirm that the patch works (for me).

And I confirm that for me this setting seems the "natural" way. I don't
claim to be representative, but the lack of this option has always be a
kind of obstacle for me when trying to give a digestable structure to my
documentation. Now that this setting is getting into Sphinx, I can
finally move into this direction. I updated the following page as a
proof of my claim:

http://lino-framework.org/api/lino.mixins.html

Thanks, Wes for integrating this.

Luc

[Luc Saffre]

On 20/04/14 03:12, Wes Turner wrote:
>

> Pull
> Request: https://bitbucket.org/birkenfeld/sphinx/pull-request/236/1456-apidoc-add-a-m-option-to-put-module/diff
>

Wes, here is a little bugfix. Add an additional empty line after the
automodule directive. Otherwise packages with empty docstring caused a
syntax error.

Luc

$ hg diff sphinx/apidoc.py
diff -r c171d4eef221 sphinx/apidoc.py
--- a/sphinx/apidoc.py Sat Apr 19 19:08:41 2014 -0500
+++ b/sphinx/apidoc.py Wed Apr 23 09:51:40 2014 +0300
@@ -98,6 +98,7 @@

if opts.modulefirst:
text += format_directive(subroot, master_package)
+ text += '\n'

# build a list of directories that are szvpackages (contain an
INITPY file)
subs = [sub for sub in subs if path.isfile(path.join(root, sub,
INITPY))]

[Takayuki Shimizukawa]

Hi,

Thanks for your propose.
The pull request #236 and suggested append-newline code has been
merged into 'default' branch.

Thanks!
--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

> --
> 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 sphinx-users...@googlegroups.com.
> To post to this group, send email to sphinx...@googlegroups.com.
> Visit this group at http://groups.google.com/group/sphinx-users.

> For more options, visit https://groups.google.com/d/optout.

[Wes Turner]

Thank you both!

Wes Turner

You received this message because you are subscribed to a topic in the Google Groups "sphinx-users" group.
To unsubscribe from this topic, visit https://groups.google.com/d/topic/sphinx-users/Bm4w7OQcWYM/unsubscribe.
To unsubscribe from this group and all its topics, send an email to sphinx-users...@googlegroups.com.

[Luc Saffre]

I pulled the default branch and ran a build: seems to work fine.
Thank you both;-)

Luc

On 05/05/14 14:38, Wes Turner wrote:
> Thank you both!
>
> Wes Turner
>
> On May 4, 2014 10:32 PM, "Takayuki Shimizukawa" <shimi...@gmail.com

> <mailto:shimi...@gmail.com>> wrote:
>
> Hi,
>
> Thanks for your propose.
> The pull request #236 and suggested append-newline code has been
> merged into 'default' branch.
>
> Thanks!
> --
> Takayuki SHIMIZUKAWA
> http://about.me/shimizukawa
>
>
> 2014-04-23 15:56 GMT+09:00 Luc Saffre <luc.s...@gmail.com

> <mailto:luc.s...@gmail.com>>:

> <mailto:sphinx-users%2Bunsu...@googlegroups.com>.

> > To post to this group, send email to sphinx...@googlegroups.com

> <mailto:sphinx...@googlegroups.com>.

> > Visit this group at http://groups.google.com/group/sphinx-users.
> > For more options, visit https://groups.google.com/d/optout.
>
> --
> You received this message because you are subscribed to a topic in
> the Google Groups "sphinx-users" group.
> To unsubscribe from this topic, visit
> https://groups.google.com/d/topic/sphinx-users/Bm4w7OQcWYM/unsubscribe.
> To unsubscribe from this group and all its topics, send an email to
> sphinx-users...@googlegroups.com

> <mailto:sphinx-users%2Bunsu...@googlegroups.com>.

> To post to this group, send email to sphinx...@googlegroups.com

> <mailto:sphinx...@googlegroups.com>.

> Visit this group at http://groups.google.com/group/sphinx-users.
> For more options, visit https://groups.google.com/d/optout.
>
> --

> 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 sphinx-users...@googlegroups.com

> <mailto:sphinx-users...@googlegroups.com>.

> To post to this group, send email to sphinx...@googlegroups.com

> <mailto:sphinx...@googlegroups.com>.

[Luc Saffre]

Hi Takayuki,

you wrote that you added that newline, and my first tests confirmed
it... but in another doctree I had the problem again and then saw that
this additional newline is still missing. The problem comes when
`modulefirst` is True and the `__init__.py` file has no docstring. I
don't know what went wrong there, but here is again a patch, against the
newest version.

Luc

[Takayuki Shimizukawa]

Hi Luc,

> but here is again a patch, against the newest version.

Strange... attached patch's difference is already applied at:
https://bitbucket.org/birkenfeld/sphinx/commits/de57208a8
Please re-confirm the your environment if you have a chance, or please
send me a smallest sample to reproduce the issue.

Thanks,

--
Takayuki SHIMIZUKAWA
http://about.me/shimizukawa

[Luc Saffre]

Strange indeed... Do the following commands describe my environment?
(issued in the top directory of my copy)

$ hg pull -u
pulling from https://bitbucket.org/birkenfeld/sphinx
searching for changes
no changes found
$ hg tip
changeset: 4717:6af68dfb4df4
tag: tip
user: shimizukawa <shimi...@gmail.com>
date: Mon May 05 16:21:32 2014 +0900
summary: update CHANGES for string length of the websupport db schema.

Luc