metalk8s
metalk8s copied to clipboard
Expose an easy way to copy-paste commands from documentation
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-copybuttonpackage todocs/requirements.inand declare its usage indocs/conf.py - [ ] Review all existing
.. code-block::directives to adjust the configuration ofcopybutton_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
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)