After listening to a lot of user feedback regarding our Plotly.py documentation, in customer workshops, on this forum, on StackOverflow, on Twitter and in person, I realized that our documentation has been too “example-oriented” and doesn’t contain enough high-level foundational information about “how things work” and “what does what”.
To remedy this, I sat down and wrote a page called The Figure Data Structure intended to capture in one place all the implicit stuff that’s not made clear enough in our documentation. This is a big, exhaustive document that explains how a figure is represented, and how all the parts of the figure relate to each other. It’s also intended as a bit of a map to the rest of the documentation: it contains over a hundred links to other pages in the docs!
As a companion document, I created a dedicated page to clearly explain what Graph Objects are, and how they relate to the figure data structure and to Plotly Express. Check out the “When to Use Graph Objects Directly” section for official guidance on
I also upgraded the Plotly Express documentation page to contain a bit more information about how PX relates to the rest of the library.
Finally, a little while ago, I created a page dedicated to Figure Factories for completeness.
These doc pages have been linked to where appropriate from dozens of example pages, and complement our existing high-level documentation on Creating and Updating Figures, Displaying Figures, Configuration and Themes and Templates.
Please keep the feedback and questions coming, in whatever format or forum suits you! We read and listen to everything and it informs our work. Please also feel free to use the “suggest an edit to this page” button at the top right corner of every documentation page, if you spot a typo, or something is missing, or you have a clearer way of explaining something!