Groups | Search | Server Info | Keyboard shortcuts | Login | Register [http] [https] [nntp] [nntps]

Groups > comp.lang.python > #97431 > unrolled thread

Re: doc-generation tool

Back to article view | Back to comp.lang.python

This discussion starts older than the indexed window; earlier articles aren't shown. The article labeled Started by below is the oldest one visible, not the original post.

Contents

  Re: doc-generation tool Ben Finney <ben+python@benfinney.id.au> - 2015-10-06 18:21 +1100

#97431 — Re: doc-generation tool

<c.buhtz@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

[toc] | [standalone]

Back to top | Article view | comp.lang.python

csiph-web