From 1ce9edfe176f25ad19d13fb63a11b4980743a523 Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Sat, 18 Nov 2023 07:20:42 -0600 Subject: [PATCH 1/5] creating a venv --- documentation/start-documenting.rst | 33 +++++++++++++++++++---------- 1 file changed, 22 insertions(+), 11 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 817f0a1cff..b97bee5732 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -81,22 +81,33 @@ Create a virtual environment ---------------------------- .. _doc-create-venv-unix: +.. _doc-create-venv-windows: -**On Unix platforms** that support :program:`make` -(including Linux, macOS and BSD), -you can create a new :mod:`venv` with the required dependencies using:: +You can create a new :mod:`venv` with the required dependencies using: - make venv +.. tab:: Unix -Building the docs with :program:`make` will automatically use this environment -without you having to activate it. + .. code-block:: shell -.. _doc-create-venv-windows: + make venv + + Building the docs with :program:`make` will automatically use this environment + without you having to activate it. + +.. tab:: macOS + + .. code-block:: shell + + make venv + + Building the docs with :program:`make` will automatically use this environment + without you having to activate it. + +.. tab:: Windows -**On Windows**, or if not using :program:`make`, -`create a new virtual environment `__ manually. -Always be sure to `activate this environment `__ -before building the documentation. + `Create a new virtual environment `__ manually. + Always be sure to `activate this environment `__ + before building the documentation. .. _building-using-make: From 3ef3eae1a5bccef48a9564b123a9f8b31a8bcc7b Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Sat, 18 Nov 2023 11:03:42 -0600 Subject: [PATCH 2/5] add getOS() script --- documentation/start-documenting.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index b97bee5732..c85cb7fcd2 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -5,6 +5,14 @@ Getting started =============== +.. raw:: html + + + .. highlight:: rest The Python language has a substantial body of documentation, much of it From 6621318abbfde91fe58baed568a80297b970ddc4 Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Mon, 20 Nov 2023 08:26:26 -0600 Subject: [PATCH 3/5] consolidate Unix and Mac venv command --- documentation/start-documenting.rst | 11 +---------- 1 file changed, 1 insertion(+), 10 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index c85cb7fcd2..31c71d732b 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -93,16 +93,7 @@ Create a virtual environment You can create a new :mod:`venv` with the required dependencies using: -.. tab:: Unix - - .. code-block:: shell - - make venv - - Building the docs with :program:`make` will automatically use this environment - without you having to activate it. - -.. tab:: macOS +.. tab:: Unix/macOS .. code-block:: shell From cab244ebb5ee900c7987485c7a896ffc99e30e1e Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Mon, 20 Nov 2023 08:30:39 -0600 Subject: [PATCH 4/5] add tabs for make commands --- documentation/start-documenting.rst | 42 ++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 6 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 31c71d732b..992987abbd 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -128,9 +128,19 @@ that attempts to emulate it as closely as practical. Make sure the environment you :ref:`created above ` is `activated `__ before running ``make.bat``. -To build the docs as HTML, run:: +To build the docs as HTML, run: - make html +.. tab:: Unix/macOS + + .. code-block:: shell + + make html + +.. tab:: Windows + + .. code-block:: dosbatch + + .\make html .. tip:: * Replace ``html`` with ``htmlview`` to open the docs in a web browser once the build completes. @@ -139,13 +149,33 @@ To build the docs as HTML, run:: browser when you make changes to reST files (Unix only). To check the docs for common errors with `Sphinx Lint`_ -(which is run on all :ref:`pull requests `), use:: +(which is run on all :ref:`pull requests `), use: + +.. tab:: Unix/macOS + + .. code-block:: shell - make check + make check + +.. tab:: Windows + + .. code-block:: dosbatch + + .\make check + +To list other supported :program:`make` targets, run: + +.. tab:: Unix/macOS + + .. code-block:: shell + + make help + +.. tab:: Windows -To list other supported :program:`make` targets, run:: + .. code-block:: dosbatch - make help + .\make help See :cpy-file:`Doc/README.rst` for more information. From 937bfcc55bd7113fd115a73e15266771aec4c141 Mon Sep 17 00:00:00 2001 From: Lance Goyke Date: Mon, 20 Nov 2023 09:21:41 -0600 Subject: [PATCH 5/5] Tabify make / make.bat section --- documentation/start-documenting.rst | 23 ++++++++++++++--------- 1 file changed, 14 insertions(+), 9 deletions(-) diff --git a/documentation/start-documenting.rst b/documentation/start-documenting.rst index 992987abbd..fec76fa977 100644 --- a/documentation/start-documenting.rst +++ b/documentation/start-documenting.rst @@ -116,17 +116,22 @@ You can create a new :mod:`venv` with the required dependencies using: Build using make / make.bat --------------------------- -A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`, -along with a :cpy-file:`Doc/make.bat` batch file for Windows -that attempts to emulate it as closely as practical. +.. tab:: Unix/macOS + + A Unix ``Makefile`` is provided, :cpy-file:`Doc/Makefile`. + +.. tab:: Windows + + A Windows ``make.bat`` is provided, :cpy-file:`Doc/make.bat`, which + attempts to emulate the Unix ``Makefile`` as closely as practical. -.. important:: + .. important:: - The Windows ``make.bat`` batch file lacks a ``make venv`` target. - Instead, it automatically installs any missing dependencies - into the currently activated environment (or the base Python, if none). - Make sure the environment you :ref:`created above ` - is `activated `__ before running ``make.bat``. + The Windows ``make.bat`` batch file lacks a ``make venv`` target. + Instead, it automatically installs any missing dependencies + into the currently activated environment (or the base Python, if none). + Make sure the environment you :ref:`created above ` + is `activated `__ before running ``make.bat``. To build the docs as HTML, run: