From 040adb4ce522701387887d6c73e78b11682789dd Mon Sep 17 00:00:00 2001 From: tboy1337 Date: Fri, 31 Oct 2025 16:56:26 +0000 Subject: [PATCH 1/4] Enhance Sphinx documentation build script with detailed comments and error handling. Updated script structure for clarity and added subroutine descriptions for better maintainability. --- docs/make.bat | 65 +++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 53 insertions(+), 12 deletions(-) diff --git a/docs/make.bat b/docs/make.bat index 9eaf9b8893..4be500bd51 100644 --- a/docs/make.bat +++ b/docs/make.bat @@ -1,21 +1,40 @@ @ECHO OFF -REM Command file for Sphinx documentation - +REM ============================================================================ +REM Sphinx Documentation Build Script for Requests +REM ============================================================================ +REM Purpose: Build Sphinx documentation in various formats (HTML, PDF, etc.) +REM Author: Requests Documentation Team +REM Date: 2025 +REM +REM This script provides a Windows interface to Sphinx documentation builds. +REM It supports multiple output formats and handles Sphinx installation checks. +REM ============================================================================ + +REM Define error code constants +set "ERROR_COMMAND_NOT_FOUND=9009" + +REM Configure Sphinx build settings if "%SPHINXBUILD%" == "" ( - set SPHINXBUILD=sphinx-build + set "SPHINXBUILD=sphinx-build" ) -set BUILDDIR=_build -set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% . -set I18NSPHINXOPTS=%SPHINXOPTS% . +set "BUILDDIR=_build" +set "ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% ." +set "I18NSPHINXOPTS=%SPHINXOPTS% ." if NOT "%PAPER%" == "" ( - set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS% - set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS% + set "ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%" + set "I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%" ) if "%1" == "" goto help if "%1" == "help" ( + REM ======================================================================== + REM Subroutine: help + REM Purpose: Display usage information and available build targets + REM Parameters: None + REM Returns: Displays help text and exits + REM ======================================================================== :help echo.Please use `make ^` where ^ is one of echo. html to make standalone HTML files @@ -43,21 +62,30 @@ if "%1" == "help" ( if "%1" == "clean" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* + del /q /s %BUILDDIR%\* 2>nul + if errorlevel 1 ( + echo.Warning: Some files could not be deleted + ) goto end ) REM Check if sphinx-build is available and fallback to Python version if any %SPHINXBUILD% 1>NUL 2>NUL -if errorlevel 9009 goto sphinx_python +if errorlevel %ERROR_COMMAND_NOT_FOUND% goto sphinx_python goto sphinx_ok +REM ============================================================================ +REM Subroutine: sphinx_python +REM Purpose: Fallback to Python module invocation if sphinx-build not found +REM Parameters: None +REM Returns: Sets SPHINXBUILD to Python module path or exits with error +REM ============================================================================ :sphinx_python -set SPHINXBUILD=python -m sphinx.__init__ +set "SPHINXBUILD=python -m sphinx.__init__" %SPHINXBUILD% 2> nul -if errorlevel 9009 ( +if errorlevel %ERROR_COMMAND_NOT_FOUND% ( echo. echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo.installed, then set the SPHINXBUILD environment variable to point @@ -69,6 +97,12 @@ if errorlevel 9009 ( exit /b 1 ) +REM ============================================================================ +REM Subroutine: sphinx_ok +REM Purpose: Confirms Sphinx is available and proceeds with build operations +REM Parameters: None +REM Returns: Continues to build target handling +REM ============================================================================ :sphinx_ok @@ -260,4 +294,11 @@ if "%1" == "pseudoxml" ( goto end ) +REM ============================================================================ +REM Subroutine: end +REM Purpose: Exit point for all build operations +REM Parameters: None +REM Returns: Terminates script execution with success code +REM ============================================================================ :end +exit /b 0 From 3a53f10c80c945b4e640a558f30002e42cd6dae4 Mon Sep 17 00:00:00 2001 From: tboy1337 Date: Fri, 31 Oct 2025 16:56:59 +0000 Subject: [PATCH 2/4] Renamed make.bat to make.cmd. --- docs/{make.bat => make.cmd} | 608 ++++++++++++++++++------------------ 1 file changed, 304 insertions(+), 304 deletions(-) rename docs/{make.bat => make.cmd} (96%) diff --git a/docs/make.bat b/docs/make.cmd similarity index 96% rename from docs/make.bat rename to docs/make.cmd index 4be500bd51..a9d3cfe130 100644 --- a/docs/make.bat +++ b/docs/make.cmd @@ -1,304 +1,304 @@ -@ECHO OFF - -REM ============================================================================ -REM Sphinx Documentation Build Script for Requests -REM ============================================================================ -REM Purpose: Build Sphinx documentation in various formats (HTML, PDF, etc.) -REM Author: Requests Documentation Team -REM Date: 2025 -REM -REM This script provides a Windows interface to Sphinx documentation builds. -REM It supports multiple output formats and handles Sphinx installation checks. -REM ============================================================================ - -REM Define error code constants -set "ERROR_COMMAND_NOT_FOUND=9009" - -REM Configure Sphinx build settings -if "%SPHINXBUILD%" == "" ( - set "SPHINXBUILD=sphinx-build" -) -set "BUILDDIR=_build" -set "ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% ." -set "I18NSPHINXOPTS=%SPHINXOPTS% ." -if NOT "%PAPER%" == "" ( - set "ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%" - set "I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%" -) - -if "%1" == "" goto help - -if "%1" == "help" ( - REM ======================================================================== - REM Subroutine: help - REM Purpose: Display usage information and available build targets - REM Parameters: None - REM Returns: Displays help text and exits - REM ======================================================================== - :help - echo.Please use `make ^` where ^ is one of - echo. html to make standalone HTML files - echo. dirhtml to make HTML files named index.html in directories - echo. singlehtml to make a single large HTML file - echo. pickle to make pickle files - echo. json to make JSON files - echo. htmlhelp to make HTML files and a HTML help project - echo. qthelp to make HTML files and a qthelp project - echo. devhelp to make HTML files and a Devhelp project - echo. epub to make an epub - echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter - echo. text to make text files - echo. man to make manual pages - echo. texinfo to make Texinfo files - echo. gettext to make PO message catalogs - echo. changes to make an overview over all changed/added/deprecated items - echo. xml to make Docutils-native XML files - echo. pseudoxml to make pseudoxml-XML files for display purposes - echo. linkcheck to check all external links for integrity - echo. doctest to run all doctests embedded in the documentation if enabled - echo. coverage to run coverage check of the documentation if enabled - goto end -) - -if "%1" == "clean" ( - for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i - del /q /s %BUILDDIR%\* 2>nul - if errorlevel 1 ( - echo.Warning: Some files could not be deleted - ) - goto end -) - - -REM Check if sphinx-build is available and fallback to Python version if any -%SPHINXBUILD% 1>NUL 2>NUL -if errorlevel %ERROR_COMMAND_NOT_FOUND% goto sphinx_python -goto sphinx_ok - -REM ============================================================================ -REM Subroutine: sphinx_python -REM Purpose: Fallback to Python module invocation if sphinx-build not found -REM Parameters: None -REM Returns: Sets SPHINXBUILD to Python module path or exits with error -REM ============================================================================ -:sphinx_python - -set "SPHINXBUILD=python -m sphinx.__init__" -%SPHINXBUILD% 2> nul -if errorlevel %ERROR_COMMAND_NOT_FOUND% ( - echo. - echo.The 'sphinx-build' command was not found. Make sure you have Sphinx - echo.installed, then set the SPHINXBUILD environment variable to point - echo.to the full path of the 'sphinx-build' executable. Alternatively you - echo.may add the Sphinx directory to PATH. - echo. - echo.If you don't have Sphinx installed, grab it from - echo.http://sphinx-doc.org/ - exit /b 1 -) - -REM ============================================================================ -REM Subroutine: sphinx_ok -REM Purpose: Confirms Sphinx is available and proceeds with build operations -REM Parameters: None -REM Returns: Continues to build target handling -REM ============================================================================ -:sphinx_ok - - -if "%1" == "html" ( - %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/html. - goto end -) - -if "%1" == "dirhtml" ( - %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. - goto end -) - -if "%1" == "singlehtml" ( - %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. - goto end -) - -if "%1" == "pickle" ( - %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the pickle files. - goto end -) - -if "%1" == "json" ( - %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can process the JSON files. - goto end -) - -if "%1" == "htmlhelp" ( - %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run HTML Help Workshop with the ^ -.hhp project file in %BUILDDIR%/htmlhelp. - goto end -) - -if "%1" == "qthelp" ( - %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; now you can run "qcollectiongenerator" with the ^ -.qhcp project file in %BUILDDIR%/qthelp, like this: - echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Requests.qhcp - echo.To view the help file: - echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Requests.ghc - goto end -) - -if "%1" == "devhelp" ( - %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. - goto end -) - -if "%1" == "epub" ( - %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The epub file is in %BUILDDIR%/epub. - goto end -) - -if "%1" == "latex" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 - echo. - echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdf" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "latexpdfja" ( - %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - cd %BUILDDIR%/latex - make all-pdf-ja - cd %~dp0 - echo. - echo.Build finished; the PDF files are in %BUILDDIR%/latex. - goto end -) - -if "%1" == "text" ( - %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The text files are in %BUILDDIR%/text. - goto end -) - -if "%1" == "man" ( - %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The manual pages are in %BUILDDIR%/man. - goto end -) - -if "%1" == "texinfo" ( - %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. - goto end -) - -if "%1" == "gettext" ( - %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The message catalogs are in %BUILDDIR%/locale. - goto end -) - -if "%1" == "changes" ( - %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 - echo. - echo.The overview file is in %BUILDDIR%/changes. - goto end -) - -if "%1" == "linkcheck" ( - %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 - echo. - echo.Link check complete; look for any errors in the above output ^ -or in %BUILDDIR%/linkcheck/output.txt. - goto end -) - -if "%1" == "doctest" ( - %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 - echo. - echo.Testing of doctests in the sources finished, look at the ^ -results in %BUILDDIR%/doctest/output.txt. - goto end -) - -if "%1" == "coverage" ( - %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 - echo. - echo.Testing of coverage in the sources finished, look at the ^ -results in %BUILDDIR%/coverage/python.txt. - goto end -) - -if "%1" == "xml" ( - %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The XML files are in %BUILDDIR%/xml. - goto end -) - -if "%1" == "pseudoxml" ( - %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 - echo. - echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. - goto end -) - -REM ============================================================================ -REM Subroutine: end -REM Purpose: Exit point for all build operations -REM Parameters: None -REM Returns: Terminates script execution with success code -REM ============================================================================ -:end -exit /b 0 +@ECHO OFF + +REM ============================================================================ +REM Sphinx Documentation Build Script for Requests +REM ============================================================================ +REM Purpose: Build Sphinx documentation in various formats (HTML, PDF, etc.) +REM Author: Requests Documentation Team +REM Date: 2025 +REM +REM This script provides a Windows interface to Sphinx documentation builds. +REM It supports multiple output formats and handles Sphinx installation checks. +REM ============================================================================ + +REM Define error code constants +set "ERROR_COMMAND_NOT_FOUND=9009" + +REM Configure Sphinx build settings +if "%SPHINXBUILD%" == "" ( + set "SPHINXBUILD=sphinx-build" +) +set "BUILDDIR=_build" +set "ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% ." +set "I18NSPHINXOPTS=%SPHINXOPTS% ." +if NOT "%PAPER%" == "" ( + set "ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%" + set "I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%" +) + +if "%1" == "" goto help + +if "%1" == "help" ( + REM ======================================================================== + REM Subroutine: help + REM Purpose: Display usage information and available build targets + REM Parameters: None + REM Returns: Displays help text and exits + REM ======================================================================== + :help + echo.Please use `make ^` where ^ is one of + echo. html to make standalone HTML files + echo. dirhtml to make HTML files named index.html in directories + echo. singlehtml to make a single large HTML file + echo. pickle to make pickle files + echo. json to make JSON files + echo. htmlhelp to make HTML files and a HTML help project + echo. qthelp to make HTML files and a qthelp project + echo. devhelp to make HTML files and a Devhelp project + echo. epub to make an epub + echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter + echo. text to make text files + echo. man to make manual pages + echo. texinfo to make Texinfo files + echo. gettext to make PO message catalogs + echo. changes to make an overview over all changed/added/deprecated items + echo. xml to make Docutils-native XML files + echo. pseudoxml to make pseudoxml-XML files for display purposes + echo. linkcheck to check all external links for integrity + echo. doctest to run all doctests embedded in the documentation if enabled + echo. coverage to run coverage check of the documentation if enabled + goto end +) + +if "%1" == "clean" ( + for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i + del /q /s %BUILDDIR%\* 2>nul + if errorlevel 1 ( + echo.Warning: Some files could not be deleted + ) + goto end +) + + +REM Check if sphinx-build is available and fallback to Python version if any +%SPHINXBUILD% 1>NUL 2>NUL +if errorlevel %ERROR_COMMAND_NOT_FOUND% goto sphinx_python +goto sphinx_ok + +REM ============================================================================ +REM Subroutine: sphinx_python +REM Purpose: Fallback to Python module invocation if sphinx-build not found +REM Parameters: None +REM Returns: Sets SPHINXBUILD to Python module path or exits with error +REM ============================================================================ +:sphinx_python + +set "SPHINXBUILD=python -m sphinx.__init__" +%SPHINXBUILD% 2> nul +if errorlevel %ERROR_COMMAND_NOT_FOUND% ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +REM ============================================================================ +REM Subroutine: sphinx_ok +REM Purpose: Confirms Sphinx is available and proceeds with build operations +REM Parameters: None +REM Returns: Continues to build target handling +REM ============================================================================ +:sphinx_ok + + +if "%1" == "html" ( + %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/html. + goto end +) + +if "%1" == "dirhtml" ( + %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. + goto end +) + +if "%1" == "singlehtml" ( + %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. + goto end +) + +if "%1" == "pickle" ( + %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the pickle files. + goto end +) + +if "%1" == "json" ( + %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can process the JSON files. + goto end +) + +if "%1" == "htmlhelp" ( + %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run HTML Help Workshop with the ^ +.hhp project file in %BUILDDIR%/htmlhelp. + goto end +) + +if "%1" == "qthelp" ( + %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; now you can run "qcollectiongenerator" with the ^ +.qhcp project file in %BUILDDIR%/qthelp, like this: + echo.^> qcollectiongenerator %BUILDDIR%\qthelp\Requests.qhcp + echo.To view the help file: + echo.^> assistant -collectionFile %BUILDDIR%\qthelp\Requests.ghc + goto end +) + +if "%1" == "devhelp" ( + %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. + goto end +) + +if "%1" == "epub" ( + %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The epub file is in %BUILDDIR%/epub. + goto end +) + +if "%1" == "latex" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + if errorlevel 1 exit /b 1 + echo. + echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdf" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "latexpdfja" ( + %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex + cd %BUILDDIR%/latex + make all-pdf-ja + cd %~dp0 + echo. + echo.Build finished; the PDF files are in %BUILDDIR%/latex. + goto end +) + +if "%1" == "text" ( + %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The text files are in %BUILDDIR%/text. + goto end +) + +if "%1" == "man" ( + %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The manual pages are in %BUILDDIR%/man. + goto end +) + +if "%1" == "texinfo" ( + %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. + goto end +) + +if "%1" == "gettext" ( + %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The message catalogs are in %BUILDDIR%/locale. + goto end +) + +if "%1" == "changes" ( + %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes + if errorlevel 1 exit /b 1 + echo. + echo.The overview file is in %BUILDDIR%/changes. + goto end +) + +if "%1" == "linkcheck" ( + %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck + if errorlevel 1 exit /b 1 + echo. + echo.Link check complete; look for any errors in the above output ^ +or in %BUILDDIR%/linkcheck/output.txt. + goto end +) + +if "%1" == "doctest" ( + %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest + if errorlevel 1 exit /b 1 + echo. + echo.Testing of doctests in the sources finished, look at the ^ +results in %BUILDDIR%/doctest/output.txt. + goto end +) + +if "%1" == "coverage" ( + %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage + if errorlevel 1 exit /b 1 + echo. + echo.Testing of coverage in the sources finished, look at the ^ +results in %BUILDDIR%/coverage/python.txt. + goto end +) + +if "%1" == "xml" ( + %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The XML files are in %BUILDDIR%/xml. + goto end +) + +if "%1" == "pseudoxml" ( + %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml + if errorlevel 1 exit /b 1 + echo. + echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. + goto end +) + +REM ============================================================================ +REM Subroutine: end +REM Purpose: Exit point for all build operations +REM Parameters: None +REM Returns: Terminates script execution with success code +REM ============================================================================ +:end +exit /b 0 From dac44379e9c9935b6c579a6a72403988ba92a6fc Mon Sep 17 00:00:00 2001 From: tboy1337 Date: Sun, 2 Nov 2025 20:36:36 +0000 Subject: [PATCH 3/4] Refactor error handling in make.cmd to use explicit errorlevel comparisons for improved clarity and consistency. --- docs/make.cmd | 48 +++++++++++++++++++++++------------------------- 1 file changed, 23 insertions(+), 25 deletions(-) diff --git a/docs/make.cmd b/docs/make.cmd index a9d3cfe130..76de839d42 100644 --- a/docs/make.cmd +++ b/docs/make.cmd @@ -63,16 +63,15 @@ if "%1" == "help" ( if "%1" == "clean" ( for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i del /q /s %BUILDDIR%\* 2>nul - if errorlevel 1 ( + if %errorlevel% neq 0 ( echo.Warning: Some files could not be deleted ) goto end ) - REM Check if sphinx-build is available and fallback to Python version if any %SPHINXBUILD% 1>NUL 2>NUL -if errorlevel %ERROR_COMMAND_NOT_FOUND% goto sphinx_python +if %errorlevel% equ %ERROR_COMMAND_NOT_FOUND% goto sphinx_python goto sphinx_ok REM ============================================================================ @@ -85,7 +84,7 @@ REM ============================================================================ set "SPHINXBUILD=python -m sphinx.__init__" %SPHINXBUILD% 2> nul -if errorlevel %ERROR_COMMAND_NOT_FOUND% ( +if %errorlevel% equ %ERROR_COMMAND_NOT_FOUND% ( echo. echo.The 'sphinx-build' command was not found. Make sure you have Sphinx echo.installed, then set the SPHINXBUILD environment variable to point @@ -105,10 +104,9 @@ REM Returns: Continues to build target handling REM ============================================================================ :sphinx_ok - if "%1" == "html" ( %SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/html. goto end @@ -116,7 +114,7 @@ if "%1" == "html" ( if "%1" == "dirhtml" ( %SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml. goto end @@ -124,7 +122,7 @@ if "%1" == "dirhtml" ( if "%1" == "singlehtml" ( %SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml. goto end @@ -132,7 +130,7 @@ if "%1" == "singlehtml" ( if "%1" == "pickle" ( %SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished; now you can process the pickle files. goto end @@ -140,7 +138,7 @@ if "%1" == "pickle" ( if "%1" == "json" ( %SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished; now you can process the JSON files. goto end @@ -148,7 +146,7 @@ if "%1" == "json" ( if "%1" == "htmlhelp" ( %SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished; now you can run HTML Help Workshop with the ^ .hhp project file in %BUILDDIR%/htmlhelp. @@ -157,7 +155,7 @@ if "%1" == "htmlhelp" ( if "%1" == "qthelp" ( %SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished; now you can run "qcollectiongenerator" with the ^ .qhcp project file in %BUILDDIR%/qthelp, like this: @@ -169,7 +167,7 @@ if "%1" == "qthelp" ( if "%1" == "devhelp" ( %SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. goto end @@ -177,7 +175,7 @@ if "%1" == "devhelp" ( if "%1" == "epub" ( %SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The epub file is in %BUILDDIR%/epub. goto end @@ -185,7 +183,7 @@ if "%1" == "epub" ( if "%1" == "latex" ( %SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished; the LaTeX files are in %BUILDDIR%/latex. goto end @@ -213,7 +211,7 @@ if "%1" == "latexpdfja" ( if "%1" == "text" ( %SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The text files are in %BUILDDIR%/text. goto end @@ -221,7 +219,7 @@ if "%1" == "text" ( if "%1" == "man" ( %SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The manual pages are in %BUILDDIR%/man. goto end @@ -229,7 +227,7 @@ if "%1" == "man" ( if "%1" == "texinfo" ( %SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo. goto end @@ -237,7 +235,7 @@ if "%1" == "texinfo" ( if "%1" == "gettext" ( %SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The message catalogs are in %BUILDDIR%/locale. goto end @@ -245,7 +243,7 @@ if "%1" == "gettext" ( if "%1" == "changes" ( %SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.The overview file is in %BUILDDIR%/changes. goto end @@ -253,7 +251,7 @@ if "%1" == "changes" ( if "%1" == "linkcheck" ( %SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Link check complete; look for any errors in the above output ^ or in %BUILDDIR%/linkcheck/output.txt. @@ -262,7 +260,7 @@ or in %BUILDDIR%/linkcheck/output.txt. if "%1" == "doctest" ( %SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Testing of doctests in the sources finished, look at the ^ results in %BUILDDIR%/doctest/output.txt. @@ -271,7 +269,7 @@ results in %BUILDDIR%/doctest/output.txt. if "%1" == "coverage" ( %SPHINXBUILD% -b coverage %ALLSPHINXOPTS% %BUILDDIR%/coverage - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Testing of coverage in the sources finished, look at the ^ results in %BUILDDIR%/coverage/python.txt. @@ -280,7 +278,7 @@ results in %BUILDDIR%/coverage/python.txt. if "%1" == "xml" ( %SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The XML files are in %BUILDDIR%/xml. goto end @@ -288,7 +286,7 @@ if "%1" == "xml" ( if "%1" == "pseudoxml" ( %SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml - if errorlevel 1 exit /b 1 + if %errorlevel% equ 1 exit /b 1 echo. echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml. goto end From 651a31f40d9e2afdd9fa7b6feb08e570f3fa1b28 Mon Sep 17 00:00:00 2001 From: tboy1337 Date: Mon, 3 Nov 2025 10:39:44 +0000 Subject: [PATCH 4/4] Update author information and version number in make.cmd for clarity and version tracking. --- docs/make.cmd | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/make.cmd b/docs/make.cmd index 76de839d42..1d7d09e843 100644 --- a/docs/make.cmd +++ b/docs/make.cmd @@ -4,8 +4,8 @@ REM ============================================================================ REM Sphinx Documentation Build Script for Requests REM ============================================================================ REM Purpose: Build Sphinx documentation in various formats (HTML, PDF, etc.) -REM Author: Requests Documentation Team -REM Date: 2025 +REM Author: ??? +REM Version: 1.0.1 REM REM This script provides a Windows interface to Sphinx documentation builds. REM It supports multiple output formats and handles Sphinx installation checks.