metalk8s icon indicating copy to clipboard operation
metalk8s copied to clipboard

Expose an easy way to copy-paste commands from documentation

Open gdemonet opened this issue 4 years ago • 1 comments

Component: docs

Why this is needed:

Code-blocks in documentation are not always easy to handle for users, as different prompts may be confusing when deciding which parts of a documented command should be copy-pasted. The Sphinx extension sphinx-copybutton exists to help with this situation.

What should be done:

  • [ ] Add the sphinx-copybutton package to docs/requirements.in and declare its usage in docs/conf.py
  • [ ] Review all existing .. code-block:: directives to adjust the configuration of copybutton_prompt_text (see how to make it a regular expression)

Test plan:

  • All code-blocks describing a command for a user to input in its terminal can be copied
  • Lines showing output of such commands or other verbatim text are not copied when clicking such button

gdemonet avatar Mar 02 '21 07:03 gdemonet

Since sphinx-copybutton has limitations, we will rather use a homemade extension as part of the Scality-built Sphinx tooling (see scality/sphinx-tools#32)

gdemonet avatar Apr 12 '21 15:04 gdemonet