-
Notifications
You must be signed in to change notification settings - Fork 2.4k
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
Improve styling of parameter tables in the docs #8618
Conversation
🪼 branch checks and previews
Install Gradio from this PR pip install https://gradio-builds.s3.amazonaws.com/afa11926c914ea76448dc8b9937278104be3a203/gradio-4.38.1-py3-none-any.whl Install Gradio Python Client from this PR pip install "gradio-client @ git+https://github.com/gradio-app/gradio@afa11926c914ea76448dc8b9937278104be3a203#subdirectory=client/python" Install Gradio JS Client from this PR npm install https://gradio-builds.s3.amazonaws.com/afa11926c914ea76448dc8b9937278104be3a203/gradio-client-1.3.0.tgz |
🦄 change detectedThis Pull Request includes changes to the following packages.
With the following changelog entry.
Maintainers or the PR author can modify the PR title to modify this entry.
|
I don't really love this for long types, they are unreadable of which we have many: https://gradio-9e0pzuzft-hugging-face.vercel.app/docs/gradio/annotatedimage I think the ParamViewer offers a better compromise: https://huggingface.co/spaces/pngwn/gradio_imageslider |
@pngwn I can split the types across multiple lines when its a union of types to avoid the issue you're mentioning Stylistically, I think gr.ParamViewer would look out of place on our docs page. And one thing I don't like like about it is how the docstrings are hidden by default -- they should always be visible to make it easier to cmd+f and find what you're looking for |
@abidlabs this looks great, though i wish there was better styling for the Default: / Required part. Maybe keep that as it is currently? |
The proposed styling looks nice! I do think it would be best if we could consolidate the desired "param table style" in the ParamViewer component. That way all parameter tables (custom components, docs, api docs) would be consistent. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Changes look good to me @abidlabs. I agree with @freddyaboulton that it would be nice to be consistent everywhere.
You have to make the changes to FunctionDoc.svelte as well (like you did for EventListeners.svelte). Right now it's still the old table styling.
I think don't think the compound/ complex types are really that readable. You can read them now but it is still almost impossible to understand the relationship between the different parts (ie nested bits, unions, etc) without some proper formatting. |
I personally think the docstrings are too long to be visible all of the time, we have too many kwargs for that. If you want to see anything else then you have an awful experience. |
Ok with changing this, but how would you suggest formatting them @pngwn?
I don't think that's the case, you can easily navigate to the different sections using the sidebar on the right. Having all of the docstrings makes it much easier to CMD+F and find what you're looking for. I strongly dislike when documentation is partially hidden as it makes search completely unreliable
Can make this change! |
For the custom component docs I used |
You are only thinking of your own usage here though. ctrl + f is only useful for power users or people who know exactly what they are looking for. It is useless for new users. Scan-ability is very important in those cases and excessively long document and minute detail make that difficult. We have search now which should support this usecase and we could visually hide the content and expand it when it gets focused. |
I actually think its the opposite! For example, we recently had a question on Discord about how to change the directory where the Python Client saves files. If you are able to search "directory" in the Python Client docs, https://www.gradio.app/docs/python-client/client, then you'd easily be able to find the answer. However, if you have to read each parameter, its going to take you longer to find the right parameter. Even if Search supported navigating to the right section, that's global search, which is not as convenient as same-page search if you are already on the right page. I really think we should always keep parameter descriptions expanded so we can keep users can always default cmd+f. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Nice! everything looks good and ctrl+f works nicely :)
Change the styling of the parameter tables in the docs to be consistent with the custom component docs, which is a lot more compact than our current docs. Because we are using the new ParamViewer component, the sections expand when a user is searching for a term that appears in a docstring:
Screen.Recording.2024-07-15.at.2.37.36.PM.mov