doc-generation tool
Ben Finney
ben+python at benfinney.id.au
Tue Oct 6 03:21:36 EDT 2015
<c.buhtz at posteo.jp> writes:
> I am confused about to much possible tools and conventions for
> doc-strings and the doc-generating tools using it.
Thank you for taking seriously the job of documenting your software!
> My code isn't about a package interface. It is just a simple
> application I want I readable documentation for.
I am confused; maybe you can help me.
You say that you *don't* want documentation for “a package interface”,
by which I think you mean the interface a programmer needs to use your
code <URL:https://en.wikipedia.org/wiki/Application_programming_interface>.
So I think for “a simple application I want readable documentation for”,
I think you are explicitly asking for documentation to be read primarily
by the (non-programmer) *users* of the application.
> I have the following needs
> - in-code doc-string should be readable for humans (e.g.
> reStructuredText, markup)
> - type of a methode-argument or class-attribute can be specified
> - no seperation between class-doc-string and
> class-attribute-doc-strings. the attribute should be described in
> the class-doc-string itself
That is all related to the documentation of very fine-grained parts of
your code; exactly the kind of documentation that is useful for a
programmer needing API documentation.
Your list, above, is *not* what I would expect for an application's
(non-programmer) end-user documentation.
Which is it? Do you want to produce API documentation, or end-user
documentation?
--
\ “I still have my Christmas Tree. I looked at it today. Sure |
`\ enough, I couldn't see any forests.” —Steven Wright |
_o__) |
Ben Finney
More information about the Python-list
mailing list