Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Generate basic API docs based on raw metadata #285

Open
ronaldoussoren opened this issue Nov 12, 2019 · 1 comment
Open

Generate basic API docs based on raw metadata #285

ronaldoussoren opened this issue Nov 12, 2019 · 1 comment
Labels
enhancement New feature or request

Comments

@ronaldoussoren
Copy link
Owner

ronaldoussoren commented Nov 12, 2019

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 ronaldoussoren added major enhancement New feature or request and removed 6.0 labels Feb 29, 2020
@ronaldoussoren
Copy link
Owner Author

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
enhancement New feature or request
Projects
None yet
Development

No branches or pull requests

1 participant