add autodocs

[pngwn]

Description

This is the bulk of the work for autodocumenting custom components. To test this you will need to install gradio_paramviewer from pip.

I will be moving this component into gradio core, so we don't need an additional dependency but I haven't quite got round to that.

I also had to remove the readme generation out while i fixed some issues but I'll add that back very shortly.

Closes #6684. Closes #6648.

🎯 PRs Should Target Issues

Before your create a PR, please check to see if there is an existing issue for this change. If not, please create an issue before you create this PR, unless the fix is very small.

Not adhering to this guideline will result in the PR being closed.

Tests

1. PRs will only be merged if tests pass on CI. To run the tests locally, please set up your Gradio environment locally and run the tests: bash scripts/run_all_tests.sh

2. You may need to run the linters: bash scripts/format_backend.sh and bash scripts/format_frontend.sh

[gradio-pr-bot]

🪼 branch checks and previews

•	Name	Status	URL
	Spaces	ready!	Spaces preview
	Website	ready!	Website preview
	Storybook	ready!	Storybook preview
	Visual tests	all good!	Build review
🦄	Changes	detected!	Details

---

Install Gradio from this PR

pip install https://gradio-builds.s3.amazonaws.com/8042e9dfb3fca7020df30ef62a0ee8bd1ba5fb79/gradio-4.14.0-py3-none-any.whl

Install Gradio Python Client from this PR

pip install "gradio-client @ git+https://github.com/gradio-app/gradio@8042e9dfb3fca7020df30ef62a0ee8bd1ba5fb79#subdirectory=client/python"

[gradio-pr-bot]

🦄 change detected

This Pull Request includes changes to the following packages.

Package	Version
@gradio/app	minor
@gradio/paramviewer	minor
gradio	minor

• Maintainers can select this checkbox to manually select packages to update.

With the following changelog entry.

add autodocs

Maintainers or the PR author can modify the PR title to modify this entry.

Something isn't right?

• Maintainers can change the version label to modify the version bump.
• If the bot has failed to detect any changes, or if this pull request needs to update multiple packages to different versions or requires a more comprehensive changelog entry, maintainers can update the changelog file directly.

[pngwn]

I might need help with some of those type errors, I'll swap toml for tomlkit since that is already being used.

[pngwn]

One or two tweaks to come but now reviewable.

[pngwn]

Sample markdown readme: https://gist.github.com/pngwn/d53d345e3887de357b5420581a534952

[freddyaboulton]

Are these imported classes actually used? If not we can remove

[pngwn]

Ah no, they won't be used.

[freddyaboulton]

Awesome PR @pngwn ! I'm still going through this but wanted to comment on some things I've noticed -

1. In the space.py the from app import demo as app line will hang forever unless the app file launches the demo in a if __name__ == '__main__' clause
2. In the README, None shows up for the badges if urls are not specified in the pyproject toml

3. I can't launch the space.py for Audio docs because there's a syntax error in the file

4. In the README, the types in the param table always show up as empty code blocks? Tried with lots of different components

[pngwn]

@freddyaboulton Can you should be the generated README.md, for the empty code block case?

[pngwn]

I have pushed up some fixes.

• I've change the demo generated demo file to contain the if __name__ == '__main__' clause, I'm not sure there is anything else we can do.
• I have done some additional cleanup on the Additional classes that we show (this was the issue with the Audio component not working)
• Opted for simpler type introspection in version prior to 3.10 which do not have great type introspection capabilities.
• More gracefully handled missing docstring or types (try the Fallback component now and it should be much nicer). Likewise plot has a missing type annotation, this should work nicely now.
• Fixed the badges
• Hide parts of the docs if there is no info to show.

[freddyaboulton]

This is great @pngwn ! Thanks for making the fixes. I can confirm they're working. I noticed the following things:

1. In docs.py I think we need to import tomlkit instead of toml

2. The parameter table no longer displays default values when I use 3.10

If I use 3.9 it works lol?

In 3.10, the "User Function" always shows Unknown for the type hint but not in 3.9

I'm seeing the same thing for the READMEs. In 3.9, the type hints get shown in the parameter table but not in 3.10.

[pngwn]

@freddyaboulton I think the recent update should address everything, I've also added some prettier output and warnings/ errors for certain cases.

• If a user is on 3.9 or below then they will get a gentle warning at the end of the run that updating python will give them a better experience.
• If there is no if __name__ == '__main__'" then the docs command errors but tells the user how to fix the problem, or how to disable the check (--suppress-demo-check)

I think CI should be green now.

[pngwn]

I have a type error in 3.8 (i thought 3.9 was out min version?). I'll see if i can figure that one out.

[freddyaboulton]

Awesome @pngwn ! Can confirm that all of the bugs noted yesterday are now gone. Only have some questions around the content now.

• Capitalize the header titles

• Kind of confused by the User function section. It says As input for Annotated image but Annotated image is really only used an output component? I think we should explain this section before going into the As input

• ParamViewer is the only component that has an As output section. I think that's a bug?

• Some components do not have a User function section (video, annotated image, model3d, etc). If it's expected, can we omit the section? Without context it's a bit confusing what this means.

[freddyaboulton]

One tiny bug is that you cannot generate docs for gr.Button. Says TypeError: Object of type type is not JSON serializable

[pngwn]

Kind of confused by the User function section. It says As input for Annotated image but Annotated image is really only used an output component?

That isn't really true in a blocks world. It might be the intention but all component can be used as inputs or outputs, there is no way to restrict this so they documentation is correct and I'd think we should focus on explaining to authors that components should work as an input or an output even if they don't do much.

ParamViewer is the only component that has an As output section. I think that's a bug?

I'll check how I'm pulling in the docstrings. We need a docstring for the return of preprocess and the param of postprocess to generate a meaningful entry.

Some components do not have a User function section (video, annotated image, model3d, etc). If it's expected, can we omit the section? Without context it's a bit confusing what this means.

It's better than nothing imo, this happens because the params / returns of processors are typed but there is no docstring (or there is a bug in pulling it in). We could use the type when there is no docstring to provide some context.

I'll take a look at Button.

[freddyaboulton]

We need a docstring for the return of preprocess and the param of postprocess to generate a meaningful entry.

Ok I think there may be a bug then, annotatedimage does not have docstrings for either pre or postprocess and it has an As input entry. Video does not have docstrings as well and it has no entry.

Regarding the User function section, I think we need to add a brief sentence or two explaining what it's trying to communicate and in what context it's relevant. Right now I find it a bit confusing.

[freddyaboulton]

Just noticed these two small things!

[freddyaboulton]

nit: I would add a comment explaining that these classes are only for demonstration purposes

[pngwn]

Oh sorry, I'll remove these before merging.

[freddyaboulton]

Typo: width syntax highlighting

[pngwn]

The reason the input/ output text was mixed up is because i got them mixed up. Annotated image docs should behave as expected now. Button thing was a bug and should be fixed.

Just gonna fix that type error in 3.8 then I'll clean up the ParamViewer docs.

[freddyaboulton]

Thanks @pngwn !

Only thing I noticed is that the markdown should also have the helpful explanation of the User Function section. Otherwise LGTM once CI is fixed. Thanks!

[pngwn]

Ah yes ofc. Thanks for catching that!