Skip to content

Commit 1035efc

Browse files
greyligreyli
authored
Add command switch tabs for Bash, CMD and Powershell with sphinx-tabs (pallets#3714)
* Enable Sphinx extension sphinx-tabs * Add command tabs for all export commands * Add command tabs for all venv commands Fix trim spaces
1 parent c5a5d9b commit 1035efc

14 files changed

Lines changed: 498 additions & 126 deletions

File tree

‎CONTRIBUTING.rst‎

Lines changed: 11 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -96,16 +96,21 @@ First time setup
9696
9797
- Create a virtualenv.
9898

99-
.. code-block:: text
99+
.. tabs::
100100

101-
$ python3 -m venv env
102-
$ . env/bin/activate
101+
.. group-tab:: macOS/Linux
103102

104-
On Windows, activating is different.
103+
.. code-block:: text
105104
106-
.. code-block:: text
105+
$ python3 -m venv env
106+
$ . env/bin/activate
107+
108+
.. group-tab:: Windows
109+
110+
.. code-block:: text
107111
108-
> env\Scripts\activate
112+
> py -3 -m venv env
113+
> env\Scripts\activate
109114
110115
- Install Flask in editable mode with development dependencies.
111116

‎docs/cli.rst‎

Lines changed: 153 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -18,20 +18,28 @@ The ``flask`` command is installed by Flask, not your application; it must be
1818
told where to find your application in order to use it. The ``FLASK_APP``
1919
environment variable is used to specify how to load the application.
2020

21-
Unix Bash (Linux, Mac, etc.)::
21+
.. tabs::
2222

23-
$ export FLASK_APP=hello
24-
$ flask run
23+
.. group-tab:: Bash
24+
25+
.. code-block:: text
26+
27+
$ export FLASK_APP=hello
28+
$ flask run
29+
30+
.. group-tab:: CMD
2531

26-
Windows CMD::
32+
.. code-block:: text
2733
28-
> set FLASK_APP=hello
29-
> flask run
34+
> set FLASK_APP=hello
35+
> flask run
3036
31-
Windows PowerShell::
37+
.. group-tab:: Powershell
3238

33-
> $env:FLASK_APP = "hello"
34-
> flask run
39+
.. code-block:: text
40+
41+
> $env:FLASK_APP = "hello"
42+
> flask run
3543
3644
While ``FLASK_APP`` supports a variety of options for specifying your
3745
application, most use cases should be simple. Here are the typical values:
@@ -128,16 +136,49 @@ If the env is set to ``development``, the ``flask`` command will enable
128136
debug mode and ``flask run`` will enable the interactive debugger and
129137
reloader.
130138

131-
::
139+
.. tabs::
132140

133-
$ FLASK_ENV=development flask run
134-
* Serving Flask app "hello"
135-
* Environment: development
136-
* Debug mode: on
137-
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
138-
* Restarting with inotify reloader
139-
* Debugger is active!
140-
* Debugger PIN: 223-456-919
141+
.. group-tab:: Bash
142+
143+
.. code-block:: text
144+
145+
$ export FLASK_ENV=development
146+
$ flask run
147+
* Serving Flask app "hello"
148+
* Environment: development
149+
* Debug mode: on
150+
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
151+
* Restarting with inotify reloader
152+
* Debugger is active!
153+
* Debugger PIN: 223-456-919
154+
155+
.. group-tab:: CMD
156+
157+
.. code-block:: text
158+
159+
> set FLASK_ENV=development
160+
> flask run
161+
* Serving Flask app "hello"
162+
* Environment: development
163+
* Debug mode: on
164+
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
165+
* Restarting with inotify reloader
166+
* Debugger is active!
167+
* Debugger PIN: 223-456-919
168+
169+
.. group-tab:: Powershell
170+
171+
.. code-block:: text
172+
173+
> $env:FLASK_ENV = "development"
174+
> flask run
175+
* Serving Flask app "hello"
176+
* Environment: development
177+
* Debug mode: on
178+
* Running on http://127.0.0.1:5000/ (Press CTRL+C to quit)
179+
* Restarting with inotify reloader
180+
* Debugger is active!
181+
* Debugger PIN: 223-456-919
141182
142183
143184
Watch Extra Files with the Reloader
@@ -149,14 +190,40 @@ additional files with the ``--extra-files`` option, or the
149190
``FLASK_RUN_EXTRA_FILES`` environment variable. Multiple paths are
150191
separated with ``:``, or ``;`` on Windows.
151192

152-
.. code-block:: none
193+
.. tabs::
153194

154-
$ flask run --extra-files file1:dirA/file2:dirB/
155-
# or
156-
$ export FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
157-
$ flask run
158-
* Running on http://127.0.0.1:8000/
159-
* Detected change in '/path/to/file1', reloading
195+
.. group-tab:: Bash
196+
197+
.. code-block:: text
198+
199+
$ flask run --extra-files file1:dirA/file2:dirB/
200+
# or
201+
$ export FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
202+
$ flask run
203+
* Running on http://127.0.0.1:8000/
204+
* Detected change in '/path/to/file1', reloading
205+
206+
.. group-tab:: CMD
207+
208+
.. code-block:: text
209+
210+
> flask run --extra-files file1:dirA/file2:dirB/
211+
# or
212+
> set FLASK_RUN_EXTRA_FILES=file1:dirA/file2:dirB/
213+
> flask run
214+
* Running on http://127.0.0.1:8000/
215+
* Detected change in '/path/to/file1', reloading
216+
217+
.. group-tab:: Powershell
218+
219+
.. code-block:: text
220+
221+
> flask run --extra-files file1:dirA/file2:dirB/
222+
# or
223+
> $env:FLASK_RUN_EXTRA_FILES = "file1:dirA/file2:dirB/"
224+
> flask run
225+
* Running on http://127.0.0.1:8000/
226+
* Detected change in '/path/to/file1', reloading
160227
161228
162229
Debug Mode
@@ -206,11 +273,31 @@ environment variables. The variables use the pattern
206273
``FLASK_COMMAND_OPTION``. For example, to set the port for the run
207274
command, instead of ``flask run --port 8000``:
208275

209-
.. code-block:: bash
276+
.. tabs::
210277

211-
$ export FLASK_RUN_PORT=8000
212-
$ flask run
213-
* Running on http://127.0.0.1:8000/
278+
.. group-tab:: Bash
279+
280+
.. code-block:: text
281+
282+
$ export FLASK_RUN_PORT=8000
283+
$ flask run
284+
* Running on http://127.0.0.1:8000/
285+
286+
.. group-tab:: CMD
287+
288+
.. code-block:: text
289+
290+
> set FLASK_RUN_PORT=8000
291+
> flask run
292+
* Running on http://127.0.0.1:8000/
293+
294+
.. group-tab:: Powershell
295+
296+
.. code-block:: text
297+
298+
> $env:FLASK_RUN_PORT = 8000
299+
> flask run
300+
* Running on http://127.0.0.1:8000/
214301
215302
These can be added to the ``.flaskenv`` file just like ``FLASK_APP`` to
216303
control default command options.
@@ -234,10 +321,28 @@ a project runner that loads them already. Keep in mind that the
234321
environment variables must be set before the app loads or it won't
235322
configure as expected.
236323

237-
.. code-block:: bash
324+
.. tabs::
238325

239-
$ export FLASK_SKIP_DOTENV=1
240-
$ flask run
326+
.. group-tab:: Bash
327+
328+
.. code-block:: text
329+
330+
$ export FLASK_SKIP_DOTENV=1
331+
$ flask run
332+
333+
.. group-tab:: CMD
334+
335+
.. code-block:: text
336+
337+
> set FLASK_SKIP_DOTENV=1
338+
> flask run
339+
340+
.. group-tab:: Powershell
341+
342+
.. code-block:: text
343+
344+
> $env:FLASK_SKIP_DOTENV = 1
345+
> flask run
241346
242347
243348
Environment Variables From virtualenv
@@ -247,13 +352,25 @@ If you do not want to install dotenv support, you can still set environment
247352
variables by adding them to the end of the virtualenv's :file:`activate`
248353
script. Activating the virtualenv will set the variables.
249354

250-
Unix Bash, :file:`venv/bin/activate`::
355+
.. tabs::
356+
357+
.. group-tab:: Bash
358+
359+
Unix Bash, :file:`venv/bin/activate`::
360+
361+
$ export FLASK_APP=hello
362+
363+
.. group-tab:: CMD
364+
365+
Windows CMD, :file:`venv\\Scripts\\activate.bat`::
366+
367+
> set FLASK_APP=hello
251368

252-
$ export FLASK_APP=hello
369+
.. group-tab:: Powershell
253370

254-
Windows CMD, :file:`venv\\Scripts\\activate.bat`::
371+
Windows Powershell, :file:`venv\\Scripts\\activate.ps1`::
255372

256-
> set FLASK_APP=hello
373+
> $env:FLASK_APP = "hello"
257374

258375
It is preferred to use dotenv support over this, since :file:`.flaskenv` can be
259376
committed to the repository so that it works automatically wherever the project

‎docs/conf.py‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
"sphinxcontrib.log_cabinet",
1919
"pallets_sphinx_themes",
2020
"sphinx_issues",
21+
"sphinx_tabs.tabs",
2122
]
2223
intersphinx_mapping = {
2324
"python": ("https://docs.python.org/3/", None),

0 commit comments

Comments
 (0)