Use tabs to display commands in macOS or Windows

[Mariatta]

Sometimes we need to display command lines that are different in macos and windows.

That's a feature in furo that lets you display such commands depends on the different environments, called Tabs: https://pradyunsg.me/furo/reference/tabs/

Using the tabs feature in furo will make the docs look cleaner.

• [x] https://devguide.python.org/#quick-reference
• [x] https://devguide.python.org/documentation/start-documenting/ https://github.com/python/devguide/pull/1224
• [x] https://devguide.python.org/documentation/devguide/ https://github.com/python/devguide/pull/1223
• [x] https://devguide.python.org/getting-started/git-boot-camp/#downloading-other-s-patches https://github.com/python/devguide/pull/1225
• [x] https://devguide.python.org/getting-started/setup-building/#install-dependencies https://github.com/python/devguide/pull/1226
• [x] https://devguide.python.org/testing/coverage/#install-coverage https://github.com/python/devguide/pull/1228
• [x] https://devguide.python.org/testing/run-write-tests/

[Mariatta]

I guess this is a feature of a sphinx extension. Regardless whether it's Furo or a Sphinx extension, I think we should make use of the feature, and I identified a few places where Tabs could be used (and there might be more)

• https://devguide.python.org/getting-started/setup-building/#install-dependencies

There are different commands for the different environments ie Linux, mac, etc.

• https://devguide.python.org/#quick-reference

The commands for macOS vs Windows can be contained in Tabs.

• https://devguide.python.org/testing/coverage/#install-coverage

It has instructions for windows, macOs, Unix.

• https://devguide.python.org/getting-started/git-boot-camp/#downloading-other-s-patches

There's a different command for windows vs macos/unix.

[hugovk]

Good idea.

For some examples using tabs, see:

• https://pip.pypa.io/en/stable/installation/
• https://packaging.python.org/en/latest/tutorials/packaging-projects/
• https://pillow.readthedocs.io/en/stable/installation.html#basic-installation

[Mariatta]

It was suggested on Discord that we use the sphinx-inline-tabs extension for this.

[pradyunsg]

Corresponding documentation: https://sphinx-inline-tabs.readthedocs.io/en/latest/

[lancegoyke]

I was playing around with this today and have some notes to share.

Todo

Another location where tabs could be used:

• https://devguide.python.org/testing/run-write-tests/#runtests

Testing environments

I'm unclear on the different commands + environment cases when running the tests. It appears there are three suitable commands:

1. ./python
2. ./python.exe
3. ./python.bat

On what systems should the user run the ./python command?

The proof of concept below shows two tabs: Windows and Unix/Linux/macOS. It sounds like we will need a third tab to describe the ./python command for testing.

Does anyone have more knowledge on this than myself?

Proof of concept

Here's a proof of concept, from the devguide/index.rst file:

Quick reference
---------------

Here are the basic steps needed to get set up and contribute a patch.
This is meant as a checklist, once you know the basics. For complete
instructions please see the :ref:`setup guide <setup>`.

1. Install and set up :ref:`Git <vcsetup>` and other dependencies
   (see the :ref:`Git Setup <setup>` page for detailed information).

5. Fork `the CPython repository <https://github.com/python/cpython>`_
   to your GitHub account and :ref:`get the source code <checkout>` using::

      git clone https://github.com/<your_username>/cpython
      cd cpython

6. Build Python, on Unix and macOS use:

   .. tab:: Unix/Linux/macOS

      .. code-block:: shell

         ./configure --with-pydebug && make -j

   .. tab:: Windows

      .. code-block:: dosbatch

         PCbuild\build.bat -e -d

   See also :ref:`more detailed instructions <compiling>`,
   :ref:`how to install and build dependencies <build-dependencies>`,
   and the platform-specific pages for :ref:`Unix <unix-compiling>`,
   :ref:`macOS`, and :ref:`Windows <windows-compiling>`.

7. :ref:`Run the tests <runtests>`:

   .. tab:: Unix/Linux/macOS

      .. code-block:: shell

         ./python.exe -m test -j3

   .. tab:: Windows

      .. code-block:: dosbatch

         ./python.bat -m test -j3

   On :ref:`most <mac-python.exe>` macOS systems, replace :file:`./python`
   with :file:`./python.exe`.  On Windows, use :file:`python.bat`.

[hugovk]

https://devguide.python.org/ says:

On most macOS systems, replace ./python with ./python.exe. On Windows, use python.bat.

So:

• ./python

is Unix,

• ./python.exe

is macOS, and

• ./python.bat

is Windows.

So shall we have those three tabs?

[hugovk]

That will mean we'll need some duplication for:

On Unix and macOS use: make patchcheck

and on Windows: .\python.bat Tools\patchcheck\patchcheck.py

Something along the lines of:

.. tab: Unix

   make patchcheck

.. tab: macOS

   make patchcheck

.. tab: Windows

   .\python.bat Tools\patchcheck\patchcheck.py

But I think that's fine: it will allow people to select the OS of their choice and they'll see the correct instructions.

[lancegoyke]

Thank you for reviewing this, @hugovk!

Okay, that was my suspicion and I agree that repetition in the tags is the right way forward.

If this Issue is unclaimed, I would be happy to work on it.

[hugovk]

Please do, you've made a good start :)

And the first PR can be small: enable the extension and add some tabs to a single page. We don't need to add tabs to the whole devguide in a single go.

[hugovk]

@lancegoyke Thanks for doing the first two pages!

We also now have some JavaScript to activate the relevant tab based on the browser's OS.

---

I've added the pages from https://github.com/python/devguide/issues/1196#issuecomment-1769096021 to a checklist in the top post, and added a couple of more /documentation pages that can have Unix vs. Windows tabs.

[hugovk]

I think we're all done here? We can re-open, or open new issues or PRs for anything else.

Thanks for all the PRs, @lancegoyke!