doesn't support constants about pydoctor

[mwhudson]

(by jelmer)
s/ignore explicitly/explicitly ignore/

[mwhudson]

(by mwhudson)
I guess it could be supported. I don't know how they would be "documented" beyond their presence.

You can always document them using @ivar or :var: or similar.

[mwhudson]

(by jelmer)
On Sun, 2010-12-05 at 22:47 +0000, Michael Hudson-Doyle wrote:

I guess it could be supported. I don't know how they would be
"documented" beyond their presence.

You can always document them using @ivar or :var: or similar.
It's mainly their presence that I would like to record. An indication
that they are undocumented would also be useful.

Cheers,

Jelmer

[mwhudson]

(by mwhudson)
On Sun, 05 Dec 2010 23:14:18 -0000, Jelmer Vernooij wrote:

On Sun, 2010-12-05 at 22:47 +0000, Michael Hudson-Doyle wrote:

I guess it could be supported. I don't know how they would be
"documented" beyond their presence.

You can always document them using @ivar or :var: or similar.
It's mainly their presence that I would like to record. An indication
that they are undocumented would also be useful.

I do have a loose plan to change the model a bit that's vaguely related,
and you've provided me an excuse to brain dump :-)

Currently, Documentables have a document_in_parent_page attribute that
indicates whether the thing being documented should have its own page or
not. I'd like to expand this to be a three-valued thing: its own page,
in the parent page as functions/methods are now and additionally "in the
parents docstring", as :ivar:s and function arguments are now.
Currently zope Attributes are documented differently from :ivar:s and
that's a bit silly. Having function arguments be documentables or at
least some kind of more structured thing would also let us emit warnings
when you document an argument a function doesn't take, something that's
the topic of another bug report I think.

Brain dump over! I think documenting module variables would fit more
naturally into this view of the world than the one we have today.

Cheers,
mwh

[mwhudson]

(by exarkun)
Is this related to supporting module variables as link targets? It seems that presently even something documented with @var cannot be the target of L{}.

[mwhudson]

(by glyph)
See also this Twisted bug: http://twistedmatrix.com/trac/ticket/6196.

[mwhudson]

(by mwhudson)
Jean-Paul Calderone writes:

Is this related to supporting module variables as link targets? It
seems that presently even something documented with @var cannot be the
target of L{}.

It actually seems that things at module level documented with @var are
not present in the rendered page currently... which doesn't seem like it
was what I intended.

[mwhudson]

(by mwhudson)
I've fixed that problem in r588. I don't know if it's worth starting to recognise constant assignments at module level and reporting them as undocumented... might be interesting. So I'll leave this bug open for now.

[gdude2002]

Has there been any progress on this? It would be extremely useful for our project

[twm]

Right now the NOT_DONE_YET constant is missing from https://twistedmatrix.com/documents/current/api/twisted.web.server.html, so I can't link to it in twisted/treq#173. It's in __all__, though.

The same thing afflicts the HTTP status code constants in twisted.web.http.

[mwhudson]

Some of the refactoring of "documentation_location" has happened. Nothing else though I'm afraid.

[mthuurne]

As of 20.7.0, module and class variables are included in the output and can be documented using @var/@cvar/@ivar at the module/class level or with a docstring immediately following the assignment.

I'm closing this now; if there is any use case not covered yet, please reopen and include an example or link to Twisted's docs.