Raise warning in plotly.offline.plot when output_type='file' and include_plotlyjs=False

[capelastegui]

When calling plotly.offline.plot(), if we use output_type='file' and include_plotlyjs=False, the resulting html file is useless, as it cannot be rendered.

I'm using plotly 3.3.0.

import plotly
import plotly.graph_objs as go

#This generates a file that includes plotly.js, and works as intended
plotly.offline.plot([go.Scatter(x=[1, 2, 3], y=[3, 2, 6])], 
                    filename='my-graph.html', output_type='file',
                   include_plotlyjs=True)

#This generates a file that doesn't include plotly.js, but fails to render
plotly.offline.plot([go.Scatter(x=[1, 2, 3], y=[3, 2, 6])], 
                    filename='my-graph-nojs.html', output_type='file', 
                    include_plotlyjs=False)

According to the documentation:

    include_plotlyjs (default=True) -- If True, include the plotly.js
        source code in the output file or string.
        Set as False if your HTML file already contains a copy of the plotly.js
        library.

I guess we are not supposed to use include_plotly_js=False and output_type='file' at the same time? If that is the case, the function should probably raise an error, rather than generating a useless file. However, I think the ideal solution would be to have the standalone html load plotly.js from an online CDN, like we do in Jupyter notebooks after calling init_notebook_mode(connected=False). So we would insert something like the following block in the html file:

<script src="https://cdn.plot.ly/plotly-latest.min.js"></script>

[jonmmease]

Hi @capelastegui , thanks for the suggestion.

Perhaps include_plotlyjs should be allowed to be set to True, False, or 'cdn'.

[jonmmease]

Hi @capelastegui,

This issue was part of the motivation for the #1234 PR. Here is the updated docstring for include_plotlyjs

    include_plotlyjs (True | False | 'cdn' | 'directory' | path - default=True)
        Specifies how the plotly.js library is included in the output html
        file or div string.

        If True, a script tag containing the plotly.js source code (~3MB)
        is included in the output.  HTML files generated with this option are
        fully self-contained and can be used offline.

        If 'cdn', a script tag that references the plotly.js CDN is included
        in the output. HTML files generated with this option are about 3MB
        smaller than those generated with include_plotlyjs=True, but they
        require an active internet connection in order to load the plotly.js
        library.

        If 'directory', a script tag is included that references an external
        plotly.min.js bundle that is assumed to reside in the same
        directory as the HTML file.  If output_type='file' then the
        plotly.min.js bundle is copied into the directory of the resulting
        HTML file. If a file named plotly.min.js already exists in the output
        directory then this file is left unmodified and no copy is performed.
        HTML files generated with this option can be used offline, but they
        require a copy of the plotly.min.js bundle in the same directory.
        This option is useful when many figures will be saved as HTML files in
        the same directory because the plotly.js source code will be included
        only once per output directory, rather than once per output file.

        If a string that ends in '.js', a script tag is included that
        references the specified path. This approach can be used to point
        the resulting HTML file to an alternative CDN.

        If False, no script tag referencing plotly.js is included. This is
        useful when output_type='div' and the resulting div string will be
        placed inside an HTML document that already loads plotly.js.  This
        option is not advised when output_type='file' as it will result in
        a non-functional html file.

I don't want to make the output_type='div' and include_plotlyjs=False combination an outright error because I don't want to break any existing workflows folks may have built around the current behavior. What do you think?

[capelastegui]

Thanks, this looks great to me. I agree that throwing a new error risks breaking stuff - perhaps a warning could be useful instead? But the new explanation in the docs may be enough.

[jonmmease]

Thanks for the feedback @capelastegui. A warning is a reasonable suggestion. I'm going to consider the enhancement part of this request done (will be released in 3.4.0), and leave the issue open with the documentation tag as a reminder to circle back around to the warning idea eventually.

[gvwilson]

Hi - we are currently trying to tidy up Plotly's public repositories to help us focus our efforts on things that will help users most. Since this issue has been sitting for several years, I'm going to close it. If it's still a concern, we'd be grateful if you could open a new issue (with a short reproducible example if appropriate) so that we can add it to our backlog. Thanks for your help - @gvwilson