Richard,
my suggestion is to convert these code comments to prosaic text in the
docstring, and to use `autodoc` and `autosummary`. Leave code comments
only for very technical details. Your example would become::
def on_connection_init(self, event):
"""Overrides :meth:`super.Class` to do something specific
bla, bla and bla.
Every session or link could have their own handler(s) if we
wanted simply by setting the "handler" slot on the given
session or link.
If a link doesn't have an event handler, the events go to its
parent session. If the session doesn't have a handler the
events go to its parent connection. If the connection doesn't
have a handler, the events go to the reactor.
"""
conn = event.connection
conn.hostname = self.host
ssn = conn.session()
snd = ssn.sender("sender")
conn.open()
ssn.open()
snd.open()
I have been experimenting with such questions for years already while
documenting my biggest project
<http://lino-framework.org/api/index.html>, but forgive me if that API
documentation still has many lacks and oddnesses, partly for historical
reasons. Any helping hand is welcome.
Luc
On 20/02/15 19:19, [email protected] wrote:
> Hi,
>
> I'm looking at using Sphinx to document example (Python) code. There are
> a couple obvious ways to do this:
>
> 1. Copy-and-paste code snippets from the example into code blocks, and
> write some text around the snippets
> 2. Use docstrings / autodoc in the code
> 3. Use literalinclude
>
> With #1, you sacrifice maintainability. #2 is really designed for
> documenting APIs. #3 doesn't actually parse anything, so if you want to
> use RST in your comments, you're stuck. Here's a short code snippet to
> illustrate what I mean:
>
> def on_connection_init(self, event):
> conn = event.connection
> conn.hostname = self.host
>
> # Every session or link could have their own handler(s) if we
> # wanted simply by setting the "handler" slot on the
> # given session or link.
> ssn = conn.session()
>
> # If a link doesn't have an event handler, the events go to
> # its parent session. If the session doesn't have a handler
> # the events go to its parent connection. If the connection
> # doesn't have a handler, the events go to the reactor.
> snd = ssn.sender("sender")
> conn.open()
> ssn.open()
> snd.open()
>
> Are there any other approaches that I should consider?
>
> Thanks!
>
> --
> 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:[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/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 [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.
