Documentation site using mkdocs

[TomPham97]

This will probably take at least a week if that's ok for you. I'll most likely ask lots of questions since I'm pretty much learning mkdocs from scratch 😅

[JoaoLages]

This will probably take at least a week if that's ok for you. I'll most likely ask lots of questions since I'm pretty much learning mkdocs from scratch 😅

Yeah, no hurries! Actually I'll be learning with/from you because I never used mkdocs 😂

[TomPham97]

So the first part of the site should be ready to publish. Apparently you just have to merge and run mkdocs gh-deploy, according to this. I'm still deciding on the way to present the API and am quite a big fan of this layout. I did some experiments here and there but wasn't completely satisfied with my decision. Let me know what you think in general!

[TomPham97]

I based the majority of customizations on squidfunk. Another helpful resource is the PyMdown Extension.

[TomPham97]

So the first part of the site should be ready to publish. Apparently you just have to merge and run mkdocs gh-deploy, according to this. I'm still deciding on the way to present the API and am quite a big fan of this layout. I did some experiments here and there but wasn't completely satisfied with my decision. Let me know what you think in general!

So I ran the mkdocs gh-deploy command already, thus you won't need to do so after merging this PR ☺️. This is what the page looks like from my fork.

[JoaoLages]

So the first part of the site should be ready to publish. Apparently you just have to merge and run mkdocs gh-deploy, according to this. I'm still deciding on the way to present the API and am quite a big fan of this layout. I did some experiments here and there but wasn't completely satisfied with my decision. Let me know what you think in general!

So I ran the mkdocs gh-deploy command already, thus you won't need to do so after merging this PR ☺️. This is what the page looks like from my fork.

The page looks really cool! I really like the layout you chose! ⭐

I have a couple of suggestions:

• Use readthedocs to host the website
• Instead of reading from README, let's create a docs/source directory:
  • Example: diffusers' main page - this is overkill, we have a simpler package :)
  • Then they also have autodoc to build parts of the documentation from docstrings in code. Check this example. I actually don't know if autodoc is something from their own doc-builder or from mkdocs, but there should be a way to have documentation from docstrings.

You can start with a dummy main page that grabs docstring from the code and I will help you filling it 😁

[TomPham97]

I have a couple of suggestions:

• Use readthedocs to host the website

I have set up the configuration files necessary for readthedocs. It would be the most convenient if you import the project yourself by connecting your readthedocs account to Github or registering using your Github account.

To include me as a maintainer of the readthedocs project, please add my username TomPham97 into the Add maintainer field. This is located in the Maintainers submenu of the Admin tab.

[TomPham97]

• I actually don't know if autodoc is something from their own doc-builder or from mkdocs, but there should be a way to have documentation from docstrings.

Autodocs appears to require HF's doc-builder. However, I'll double check once more tomorrow to make sure if it could work as a standalone tool. Mkdocstrings is already available with the current setup and can be called with a tripple colon ::: followed by the python script/function name. Maybe we could start with the Txt2Img explainer and see whether mkdocstrings is sufficient? What do you think?

[TomPham97]

• Instead of reading from README, let's create a docs/source directory

I'll start a new PR for this, so the current PR doesn't get too cluttered.

[JoaoLages]

I have set up the configuration files necessary for readthedocs. It would be the most convenient if you import the project yourself by connecting your readthedocs account to Github or registering using your Github account.

To include me as a maintainer of the readthedocs project, please add my username TomPham97 into the Add maintainer field. This is located in the Maintainers submenu of the Admin tab.

Done! This is very easy when you send all the needed links! 😂 🙏

[JoaoLages]

• I actually don't know if autodoc is something from their own doc-builder or from mkdocs, but there should be a way to have documentation from docstrings.

Autodocs appears to require HF's doc-builder. However, I'll double check once more tomorrow to make sure if it could work as a standalone tool. Mkdocstrings is already available with the current setup and can be called with a tripple colon ::: followed by the python script/function name. Maybe we could start with the Txt2Img explainer and see whether mkdocstrings is sufficient? What do you think?

Definitely! From this example you sent, I think we can definitely work only with mkdocstrings Thanks a lot for all your effort, amazing work! ⭐ 🚀

[JoaoLages]

Looking at https://tompham97.github.io/diffusers-interpret/api/explainer/#explainer.BasePipelineExplainer.call, it seems that:

1. We need to add a docstring to __init__ because it does not appear here - also, is it possible for __init__ to appear before __call__? it would make sense but not super important

2. Can we format this part To appear like this? It would make it easier to read. No big issue if not possible.

3. Seems like we need to remove from the types. Also, is it possible to put some links here? For example a link for theAttributionMethodsclass. Also, we can remove theoptionalpart since we have theDefault` column

4. Return type is bugged, how do we fix it?

[JoaoLages]

Also, this scrollbar makes the documentation hard to read. Can we change the template to get rid of the horizontal scrollbar?

[TomPham97]

I'm currently on vacation and will attempt to answer your questions in 3 days or so. Thank you for your patience ☺️

[TomPham97]

Looking at https://tompham97.github.io/diffusers-interpret/api/explainer/#explainer.BasePipelineExplainer.call, it seems that:

1. We need to add a docstring to __init__ because it does not appear here - also, is it possible for __init__ to appear before __call__? it would make sense but not super important
2. Can we format this part To appear like this? It would make it easier to read. No big issue if not possible.
3. Seems like we need to remove from the types. Also, is it possible to put some links here? For example a link for theAttributionMethodsclass. Also, we can remove theoptionalpart since we have theDefault` column
4. Return type is bugged, how do we fix it?

So I discovered the helpful options for rendering the docstring. I'm currently doing some tests to verify their functionalities.

[TomPham97]

1. We need to add a docstring to __init__ because it does not appear here - also, is it possible for __init__ to appear before __call__? it would make sense but not super important

There's indeed this option that you're looking for. To display the __init__ method, the docstring from explainer.py needs to be formatted appropriately, which is addressed in PR #20 . For now, it would be best if you could merge this PR as a base for the documentation site.

[TomPham97]

Also, this scrollbar makes the documentation hard to read. Can we change the template to get rid of the horizontal scrollbar?

I've set this template option to list instead of table. You can view the change here. If you don't see any changes, I suggest opening the link in an igcognito window to reset the browser's previous cache.

[TomPham97]

2. Can we format this part To appear like this? It would make it easier to read. No big issue if not possible.

Is this option what you were looking for? Setting it to true instead of the default false will yield something like this:

[JoaoLages]

Also, this scrollbar makes the documentation hard to read. Can we change the template to get rid of the horizontal scrollbar?

I've set this template option to list instead of table. You can view the change here. If you don't see any changes, I suggest opening the link in an igcognito window to reset the browser's previous cache.

Nice! I prefer it this way!

[JoaoLages]

2. Can we format this part To appear like this? It would make it easier to read. No big issue if not possible.

Is this option what you were looking for? Setting it to true instead of the default false will yield something like this:

better! can we add a \n for each parameter?