search

twisted / pydoctor

This is pydoctor, an API documentation generator that works by static analysis.
https://pydoctor.readthedocs.io
Other
190 stars 51 forks source link

Generate JSON of native docstrings #93

Open ericholscher opened 9 years ago

ericholscher commented 9 years ago

It would be awesome to be able to generate a JSON representation of the raw docstrings.

Something along the lines of epyparse: https://github.com/averagehuman/python-epyparse

mwhudson commented 9 years ago

I think this make sense, on the face of it. Can you give a couple of more explicit use cases though? I'm lacking in imagination this evening :-)

ericholscher commented 9 years ago

The main use case is to pydoctor as more of a library to pull docstrings and structure out, and render it in your own output format. Having a representation that is output agnostic is useful for lots of things, including testing, portability, and downstream tooling.

On Sun, Jun 7, 2015 at 3:01 AM, Michael Hudson-Doyle < notifications@github.com> wrote:

I think this make sense, on the face of it. Can you give a couple of more explicit use cases though? I'm lacking in imagination this evening :-)

— Reply to this email directly or view it on GitHub https://github.com/twisted/pydoctor/issues/93#issuecomment-109731743.

Eric Holscher Maker of the internet residing in Portland, Oregon http://ericholscher.com

ericholscher commented 9 years ago

The main use case I have for it, is to be able to include parse-only Python docs in a Sphinx project. I want to output RST directly, not use pydoctor's HTML output, and then have an intersphinx inventory.

On Sun, Jun 7, 2015 at 8:22 AM, Eric Holscher eric@ericholscher.com wrote:

The main use case is to pydoctor as more of a library to pull docstrings and structure out, and render it in your own output format. Having a representation that is output agnostic is useful for lots of things, including testing, portability, and downstream tooling.

On Sun, Jun 7, 2015 at 3:01 AM, Michael Hudson-Doyle < notifications@github.com> wrote:

I think this make sense, on the face of it. Can you give a couple of more explicit use cases though? I'm lacking in imagination this evening :-)

— Reply to this email directly or view it on GitHub https://github.com/twisted/pydoctor/issues/93#issuecomment-109731743.

Eric Holscher Maker of the internet residing in Portland, Oregon http://ericholscher.com

Eric Holscher Maker of the internet residing in Portland, Oregon http://ericholscher.com

mwhudson commented 9 years ago

OK, so we're basically talking about serializing a system and it's collection of Documentable subclasses? Sounds plausible enough. There is support for picking, but it doesn't work very well (even like 8 years ago when I started this I knew better than to use pickle...)

What other structure do you want other than location/"fullname" and docstring? I guess class hierarchy stuff, but what about zope.interface things?

Would JSON output with a JSON schema for documentation be appropriate?

ericholscher commented 9 years ago

I simply mean, render the context that goes into the HTML as JSON rather than render it into HTML. Presumably it ends up in a string-based data structure before it gets turned into HTML, so you just need to output whatever this is.

On Sun, Jun 7, 2015 at 5:30 PM, Michael Hudson-Doyle < notifications@github.com> wrote:

OK, so we're basically talking about serializing a system and it's collection of Documentable subclasses? Sounds plausible enough. There is support for picking, but it doesn't work very well (even like 8 years ago when I started this I knew better than to use pickle...)

What other structure do you want other than location/"fullname" and docstring? I guess class hierarchy stuff, but what about zope.interface things?

Would JSON output with a JSON schema for documentation be appropriate?

— Reply to this email directly or view it on GitHub https://github.com/twisted/pydoctor/issues/93#issuecomment-109817469.

Eric Holscher Maker of the internet residing in Portland, Oregon http://ericholscher.com

mwhudson commented 9 years ago

The data structures are not particularly simple, no :-)

tristanlatr commented 3 years ago

This exists: https://github.com/NiklasRosenstein/docspec .

I've done a quick review of their JSON specification. We'll definitely need to extend it to add Interface support, and other kinds of stuff like:

I think it would be possible implement System.dump() and System.load() methods that would create/read a JSON object like specified by this format, once we've added the required feature to the NiklasRosenstein/docspec repo, or we'de have to integrate a modified copy into pydoctor.