[DISCUSS] Should we use terminal prompts in documentation?

[Mark Mikofski]

This topic recently came up in PR #922

https://github.com/pvlib/pvlib-python/pull/922#discussion_r386485277

The question is whether or not to use terminal prompts like $ in the documentation. As I said in the next comment:

I think one good reason to use a prompt, is to distinguish between the terminal (CMD: >, BaSH: $, etc) and a Python interpreter: >>> -- which might seem obvious to one of us, but I have found it is a frequent stumbling block for new users. We say, "type pytest pvlib," but not where, so they type this in Python, instead of a terminal.

But I was wondering what others thought about this, and whether it is really necessary. I hesitate to make an issue if it's a non-issue.

thanks! 

[Kevin Anderson]

I have also seen new users assume all code snippets go into the python REPL, so I do think a prompt character and explanation would be an improvement in that context.  However I'm often frustrated when trying to copy/paste a code snippet into an editor and the prompt characters come along with it.  If we do add prompts, it would be nice to generate the HTML such that it's possible to copy the code by itself without the characters, perhaps the prompt characters don't get selected when highlighting a code block. 

Five seconds of googling found these:

- https://github.com/sbrunner/sphinx-prompt

- https://github.com/choldgraf/sphinx-copybutton

Kevin

[Mark Mikofski]

+1 for sphinx-copybutton

-1 for sphinx-prompt

FYI: copybutton has a skip-text option to remove Python prompts like >>>, although there's an open issue for multi-line input, which may use "..."

Also, there is a way to automatically hide prompts in sphinx, but I don't know how to activate it.

For example, the Python docs themselvs have this: https://docs.python.org/3/tutorial/inputoutput.html

And they're also in the sphinx/numpy docs: https://docs.scipy.org/doc/scipy/reference/generated/scipy.interpolate.interp2d.html

So if we can enable this feature, then users can just highlight text without the prompt.

It looks like the ability to hide the prompt may not be available in RTD? Unclear?

https://github.com/readthedocs/sphinx_rtd_theme/issues/167

apparently the feature is enable by this javascript: https://docs.python.org/3/_static/copybutton.js

Chris Holdgraf's sphinx extension is unfortunately similarly named, "sphinx-copybutton" but they are _not_ the same.

The copybutton.js scipt is part of the scipy-sphinx-theme extension:

https://github.com/scipy/scipy-sphinx-theme/blob/master/_theme/scipy/static/js/copybutton.js

which states that it is copied from the PSF cpython here (moved from cpython to python-doc-theme in 2017):

https://github.com/python/python-docs-theme

FYI: python-doc-theme is on PyPI here:

https://pypi.org/project/python-docs-theme/

So, what to do? I see a few options:

1. use chris holdgraphs sphinx-copybutton extension

2. use the python-doc-theme or something similar

3. do nothing.

That doesn't answer the question about what to use for terminal prompts. I only looked through sphinx docs, and they use the $ terminal prompt at least a few places.

IMO, we might skip the terminal prompt and just say explicitly, enter this into a terminal, but for python repl maybe we use ">>>" and the python-doc-theme?