86 lines
2.9 KiB
ReStructuredText
86 lines
2.9 KiB
ReStructuredText
Contributing
|
|
============
|
|
|
|
See the Pallets `detailed contributing documentation <contrib_>`_ for many ways
|
|
to contribute, including reporting issues, requesting features, asking or
|
|
answering questions, and making PRs.
|
|
|
|
.. _contrib: https://palletsprojects.com/contributing/
|
|
|
|
Copy-to-Clipboard Buttons
|
|
-------------------------
|
|
|
|
The Flask docs are built with Sphinx. Follow the steps below to add a copy
|
|
button to every code block by using the ``sphinx-copybutton`` extension.
|
|
|
|
.. versionchanged:: 3.2
|
|
Added copy button setup instructions for the documentation build.
|
|
|
|
1. Install the extension in your activated virtual environment:
|
|
|
|
.. code-block:: console
|
|
|
|
(venv) $ pip install sphinx-copybutton
|
|
|
|
If you keep documentation dependencies in ``pyproject.toml`` (group
|
|
``docs``) or another requirements file, add ``sphinx-copybutton`` there and
|
|
regenerate any lock files (for example ``uv lock``) so other contributors get
|
|
the dependency automatically.
|
|
|
|
2. Enable the extension in ``docs/conf.py`` by appending it to
|
|
``extensions``:
|
|
|
|
.. code-block:: python
|
|
|
|
extensions = [
|
|
"sphinx.ext.autodoc",
|
|
"sphinx.ext.extlinks",
|
|
"sphinx.ext.intersphinx",
|
|
"sphinx_copybutton",
|
|
"sphinxcontrib.log_cabinet",
|
|
"sphinx_tabs.tabs",
|
|
"pallets_sphinx_themes",
|
|
]
|
|
|
|
3. (Optional) Strip interactive prompts from the copied text so readers get
|
|
clean commands. Add the following configuration near the bottom of the
|
|
general settings in ``docs/conf.py``:
|
|
|
|
.. code-block:: python
|
|
|
|
copybutton_prompt_text = r">>> |\.\.\. |\$ "
|
|
copybutton_prompt_is_regexp = True
|
|
copybutton_only_copy_prompt_lines = False
|
|
|
|
Tweak ``copybutton_prompt_text`` if your docs use different prompt strings.
|
|
|
|
4. Build the documentation locally to confirm everything works:
|
|
|
|
.. code-block:: console
|
|
|
|
(venv) $ make html
|
|
|
|
This runs ``sphinx-build`` via the docs ``Makefile`` and places HTML under
|
|
``docs/_build/html``. Resolve any warnings or errors before committing.
|
|
|
|
5. Test the copy button in the generated site. Open the landing page in your
|
|
browser (macOS example shown):
|
|
|
|
.. code-block:: console
|
|
|
|
(venv) $ open docs/_build/html/index.html
|
|
|
|
Hover over any code block—each one now shows a copy icon. Click the icon,
|
|
paste into a terminal or editor, and verify that prompts such as ``>>>`` and
|
|
``$`` were stripped if you enabled the regex configuration.
|
|
|
|
Best Practices
|
|
~~~~~~~~~~~~~~
|
|
|
|
* Run ``make clean`` (or delete ``docs/_build``) when you switch branches to
|
|
avoid stale artifacts.
|
|
* Consider ``SPHINXOPTS=-W make html`` to treat warnings as errors and keep the
|
|
docs healthy.
|
|
* Use ``sphinx-autobuild`` for faster authoring loops: ``uv run -m sphinx_autobuild docs docs/_build/dirhtml``.
|
|
* Preview multiple sections after theme or JavaScript changes to ensure the copy
|
|
button renders consistently everywhere.
|