ronaldoussoren / pyobjc

The Python <-> Objective-C Bridge with bindings for macOS frameworks
https://pyobjc.readthedocs.io
563 stars 47 forks source link

Generate basic API docs based on raw metadata #285

Open ronaldoussoren opened 5 years ago

ronaldoussoren commented 5 years ago

It should be possible to generate API documentation for use in the sphinx docs based on the metadata. These would necessarily be pretty minimal, just a list of APIs with at best a link to Apple’s documentation for that API.

This is somewhat related to #198, both issues probably require slightly richer raw metadata to be truly useful. Interesting information to add to the raw metadata:

  1. The class name for object arguments (id, type encoding '@')
  2. Enum information (both to group enum values, and to document that an API uses the enum)

Also investigate how to merge the generated API documentation with manual documentation for extra bits added by PyObjC (such as APIs added using objc.addConvenienceForClass).

P.S. Writing full API documentation for the framework bindings is out of scope, there’s no way I can keep up with Apple.

ronaldoussoren commented 4 years ago

Current plan is to enhance the "fwinfo" files used by objective.metadata, both with more information extracted from sources and with information currently in the apinotes documents.

When generate sphinx module documents from these (and make the apinotes documents links to the generated module documentation).

What I haven't thought much about yet: How to include information about additional "convenience" methods (dunder methods, methods mirroring Python standards, ...).

Note that these will never be as useful as proper handwritten documentation, but that's