Path: csiph.com!goblin3!goblin1!goblin.stu.neva.ru!uio.no!news.tele.dk!news.tele.dk!small.news.tele.dk!newsgate.cistron.nl!newsgate.news.xs4all.nl!nzpost1.xs4all.net!not-for-mail
Return-Path: <python-python-list@m.gmane.org>
X-Original-To: python-list@python.org
Delivered-To: python-list@mail.python.org
X-Spam-Status: OK 0.036
X-Spam-Evidence: '*H*': 0.93; '*S*': 0.00; '*not*': 0.07; 'api': 0.09; 'received:80.91': 0.09; 'received:80.91.229': 0.09; 'received:gmane.org': 0.09; 'received:list': 0.09; 'explicitly': 0.15; 'readable': 0.16; 'received:80.91.229.3': 0.16; 'received:plane.gmane.org': 0.16; 'subject:doc': 0.16; 'subject:generation': 0.16; 'looked': 0.16; 'attribute': 0.18; 'programmer': 0.18; 'specified': 0.23; 'header:User-Agent:1': 0.26; 'header:X-Complaints-To:1': 0.26; '(e.g.': 0.27; 'interface': 0.29; 'documenting': 0.29; 'url:wikipedia': 0.29; 'wright': 0.29; 'url:wiki': 0.30; 'code': 0.30; 'related': 0.32; 'maybe': 0.33; 'useful': 0.33; 'conventions': 0.33; 'primarily': 0.35; 'asking': 0.35; "isn't": 0.35; 'list,': 0.36; 'should': 0.36; 'url:org': 0.36; 'possible': 0.36; 'to:addr:python-list': 0.36; 'subject:: ': 0.37; 'expect': 0.37; 'say': 0.37; 'received:org': 0.37; 'itself': 0.38; 'thank': 0.38; 'mean': 0.38; 'sure': 0.39; 'url:en': 0.39; 'application': 0.39; 'subject:-': 0.39; 'to:addr:python.org': 0.40; 'still': 0.40; 'your': 0.60; 'above,': 0.63; 'needing': 0.63; 'between': 0.65; 'christmas': 0.66; 'today.': 0.67; '_o__)': 0.84; 'end-user': 0.84; 'humans': 0.84; 'received:125': 0.84; 'subject:tool': 0.84
X-Injected-Via-Gmane: http://gmane.org/
To: python-list@python.org
From: Ben Finney <ben+python@benfinney.id.au>
Subject: Re: doc-generation tool
Date: Tue, 06 Oct 2015 18:21:36 +1100
References: <3nTSLL1kfbz5vNF@dovecot03.posteo.de>
Mime-Version: 1.0
Content-Type: text/plain; charset=utf-8
Content-Transfer-Encoding: 8bit
X-Gmane-NNTP-Posting-Host: jigong.madmonks.org
X-Public-Key-ID: 0xAC128405
X-Public-Key-Fingerprint: 517C F14B B2F3 98B0 CB35  4855 B8B2 4C06 AC12 8405
X-Public-Key-URL: http://www.benfinney.id.au/contact/bfinney-pubkey.asc
X-Post-From: Ben Finney <bignose+hates-spam@benfinney.id.au>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4 (gnu/linux)
Cancel-Lock: sha1:zKoc7E8ZVFUFf7plu+FUmHH6zz0=
X-BeenThere: python-list@python.org
X-Mailman-Version: 2.1.20+
Precedence: list
List-Id: General discussion list for the Python programming language <python-list.python.org>
List-Unsubscribe: <https://mail.python.org/mailman/options/python-list>, <mailto:python-list-request@python.org?subject=unsubscribe>
List-Archive: <http://mail.python.org/pipermail/python-list/>
List-Post: <mailto:python-list@python.org>
List-Help: <mailto:python-list-request@python.org?subject=help>
List-Subscribe: <https://mail.python.org/mailman/listinfo/python-list>, <mailto:python-list-request@python.org?subject=subscribe>
Newsgroups: comp.lang.python
Message-ID: <mailman.411.1444116115.28679.python-list@python.org>
Lines: 44
NNTP-Posting-Host: 2001:888:2000:d::a6
X-Trace: 1444116115 news.xs4all.nl 23770 [2001:888:2000:d::a6]:51857
X-Complaints-To: abuse@xs4all.nl
Xref: csiph.com comp.lang.python:97431

<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