Submodules to autosummary, and respect __all__ (patch)

[shimizukawa]

== 1.) I implemented //submodules// to autosummary extension. ==

See the following diff. After that patch one can use them in module.rst for example:

#!plaintext
       {% block modules %}
       {% if modules %} 
       .. rubric:: Submodules

       .. autosummary::

       {% for submodule in modules %}
          {{ fullname }}.{{ submodule }}
       {% endfor %}
       {% endif %}
       {% endblock %}

== 2.) I made the module to respect all ==
//If the module being summarized has defined all, otherwise it fallbacks to dir() that was used before.

They are both in same patch, because they depend on each other somewhat, and they belong to same section of code.

== As a bonus. ==
After that patch, one can //generate// whole documentation of //package//, all classes/submodules/functions etc with one custom module.rst. I will paste it to comment of this Issue, so others can use it also. This beats the living crap out of EpyDoc any day :) Even for small projects...

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/317
• Originally reported by: ciantic
• Originally created at: 2010-01-11T18:57:04.808

[shimizukawa]

From ciantic on 2010-01-11 18:05:57+00:00

Here is the module.rst I speaked in Bonus topic, it's rather obvious since it just includes :toctree: for all of the subthingies

{{{
{{ fullname }}
{{ underline }}

.. automodule:: {{ fullname }}

{% block functions %}
{% if functions %}
.. rubric:: Functions

.. autosummary::
:toctree: {{ fullname }}/functions

{% for item in functions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block modules %}
{% if modules %}
.. rubric:: Submodules

.. autosummary::
:toctree: {{ fullname }}/submodules

{% for submodule in modules %}
{{ fullname }}.{{ submodule }}
{% endfor %}
{% endif %}
{% endblock %}

{% block classes %}
{% if classes %}
.. rubric:: Classes

.. autosummary::
:toctree: {{ fullname }}/classes

{% for item in classes %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}

{% block exceptions %}
{% if exceptions %}
.. rubric:: Exceptions

.. autosummary::
:toctree: {{ fullname }}/exceptions

{% for item in exceptions %}
{{ item }}
{%- endfor %}
{% endif %}
{% endblock %}
}}}

With that module.rst creating documentation just from docstrings is easy piecy. You only include in index.rst the package:
{{{

API Reference

.. autosummary::
:toctree: api

yourpackage
}}}
Now all documentation for your project is generated, as long as you remember to set autosummary_generate = True in conf.py.

[shimizukawa]

From ciantic on 2010-01-11 19:43:12+00:00

Hmm, okay, apparently one cannot replace files...

So here is second version, for some reason the original author of autosummary also thought it is a good idea to mask module attributes, why? I want to document also module attributes...

[shimizukawa]

From ciantic on 2010-01-13 17:10:36+00:00

Third installment, this has legacy mode, when tuning respect_all=False (Though as from TODO one can see, it is not configurable anyway yet).

[shimizukawa]

From ciantic on 2010-03-05 16:21:45+00:00

Okay, I decided that "fixing" autosummary is not the right thing, since it would be almost impossible to make it backwards compatible at this extent I wanted. So I created own extension that is //directly aimed at generating project package/module documentations//.

My extension: Sphinkydoc can be found in http://github.com/Ciantic/sphinkydoc and so far it is only alpha and I've tested it only against tip of Sphinx.

It automatically reads all modules/packages, generates documentation from docstrings and uses your project files such as INSTALL, README, CHANGES, COPYING, LICENSE to complement the generated documentation.

Though, I think the generation code in my extension is far more cleaner, as it is separated to logical functions. See the generation code at http://github.com/Ciantic/sphinkydoc/blob/master/src/sphinkydocext/generate.py where various documentation generations tooks place.

[shimizukawa]

From Georg Brandl on 2010-04-06 09:03:17+00:00

Thanks for your work! A look at Sphinkydoc is already on my to-do list. Assuming you're still interested in contributing to Sphinx itself (I've sadly neglected your work a bit because I had to concentrate on getting domains ready), I think we can target this to version 1.1.

[shimizukawa]

From ciantic on 2010-04-06 19:47:41+00:00

No harm done, I think this separate extension approach is much better. Since autosummary is good for creating the tables at some level, but for actual documentation generation it was not suitable.

Basically Sphinkydoc is split on two parts:

Generating sphinx configuration //the actual conf.py// using sphinkydoc.py (script) which to some degree is a rather extreme.

Actual documentation for helper pages (such as LICENSE, COPYING, ...) and modules, packages are generated using sphinkydocext (extension).

As a pure extension it is not as useful as a script. My extension is not release ready, no single tag is yet added...

Nevertheless one should be able to try it (see README) by fetching the source (adding src to pythonpath) and going to docs/ directory underneath sphinkydoc dir and running "sphinkydoc.py sphinkydocext"... It does many kinds of documentation generation.

I'm very much interested to develop sphinkydoc forwards as it currently works for all of my small projects. The main improvement I'm working on is to be able to read project's setup.py and incorporate interesting information to documentation automatically. I haven't had time lately to improve it.

[shimizukawa]

From Georg Brandl on 2014-01-10 19:36:39+00:00

This has lingered too long (my fault) and won't apply anymore.