Building docs locally using Windows PowerShell

[stellaprins]

I'm using Windows PowerShell, and having some issues with building-the-documentation-locally.

The make command is not recognized in PowerShell.

Using the sphinx-build command directly works (make html does the same as sphinx-build -b html source build). But perhaps an easier work around it to install make for Windows. I've installed GNU Make for Windows using Chocolatey website and have no problems running make html and make linkcheck now.

However, am running into some issues when trying to run make clean

rm -rf ./build
process_begin: CreateProcess(NULL, rm -rf ./build, ...) failed.
make (e=2): The system cannot find the file specified.

My work around for make clean is to run the following commands in the Windows PowerShell:

Remove-Item -Recurse -Force .\build
Remove-Item -Force .\source\api_index.rst
Remove-Item -Recurse -Force .\source\api
Remove-Item -Recurse -Force .\source\examples
Remove-Item -Force .\source\snippets\admonitions.md

[niksirbi]

Thanks for reporting this @stellaprins!
It's important that our instructions on how to contribute documentation are valid for all platforms.
@lochhh is the one who wrote configured our docs to work with make. She's also a Windows user, so I'm sure she knows more about this than I do.

She's away this week, but I'll make sure to ask her about this when she's back.

[lochhh]

Thanks @stellaprins for reporting this! The make clean issue you're running into now is because you're using GNU Make, which executes the Makefile (containing rm -rf that isn't recognised in Windows) rather than the make.bat intended for Windows.

I'm suspecting the initial "make command is not recognized in PowerShell" error is because you ran this in a directory that doesn't contain make.bat. If make.bat exists in the directory from which make is called, Windows should automatically execute make.bat, as long as there aren't any other make commands with higher precedence in the session.
A quick way to verify this (before you uninstall GNU Make) is to simply rename make.bat to something else, e.g. makey.bat.
If you run Get-Command makey now, you should see that makey.bat is executed:

CommandType Name Version Source

---

Application makey.bat ... ...

[stellaprins]

@lochhh I think it has to do with my PowerShell settings.

I tried running make from the docs dir with the make.bat file. To double check, I've renamed the file to makey.bat, and can execute html, clean, and linkcheck using .\makey.bat html, .\makey.bat clean, and .\makey.bat linkcheck.

But when I run Get-Command makey or something like makey clean I get the following.

makey: The term 'makey' is not recognized as a name of a cmdlet, function, script file, or executable program.
Check the spelling of the name, or if a path was included, verify that the path is correct and try again.

Suggestion [3,General]: The command "makey" was not found, but does exist in the current location.
PowerShell does not load commands from the current location by default (see ''Get-Help about_Command_Precedence'').

I don't mind typing .\makey.bat but I guess adding the docs directory to my path could allow me to use the makey command without typing .\makey.bat.

[lochhh]

Thanks again for checking @stellaprins ! We probably shouldn't assume . is in PATH for everyone.
We can update the documentation to

1. have separate commands for
   • Unix and Windows CMD: make html (or just omit CMD?)
   • Windows PowerShell: .\make html

or

2. keep the same make html command and add a note that says PowerShell users should prefix make commands with .\ (PR Add make docs note for PowerShell users #430)