Black Lives Matter. Please consider donating to Black Girls Code today.

Documentation/docstrings on a dash proyect

How do you do your documentation on your dash project? Do you use docstrings? sphinx? google style guidelines?
I am looking for some examples on how to do that. The apps that are on the dash app gallery are documented in a simple way and I don’t know if this is a good practice or if it’s required to do something more sophisticated.

I understand that finally the documentation depends on the developer and the requirements, but I am only looking for guidance and best practices.

Thank you!

Hi @pradel, the dash documentation https://dash.plot.ly/ is a very big multipage Dash app. You can find its source code on https://github.com/plotly/dash-docs (the documentation pages are in the dash_docs/tutorial directory). The big advantage of this solution is that your doc is reactive and interactive since it’s a Dash app, therefore you can demonstrate the parameters of the different components and how they interact together. However, you have to host your documentation (heroku is a free solution for this), since you need flask to run your application, so you cannot just dump a set of html pages somewhere (Github pages for example) as for a static doc.

About docstrings, for documenting the API we use indeed docstrings which are parsed and formatted (see https://github.com/plotly/dash-docs/blob/master/dash_docs/tutorial/utils/convert_props_to_list.py).

Sphinx is not used for the Dash documentation, but it is used for documenting the API of the plotly.py library https://plot.ly/python-api-reference/.

For the Dash apps of the gallery, you may have noticed that there is often a dcc.Tab with documentation (and other tabs for the interaction with data), it’s a useful trick to have enough space for the documentation without cluttering the dashboard with a lot of information. Also, dcc.Markdown is a convenient way to write well-formatted text such as documentation.

I’m sure other users will have other tips and tricks to share !

It’s very cool that the dash documentation is itself a dash app :slight_smile:
Thanks for the suggestions, I’ll look what’s best for my project.