Improve support for building docs on Windows (mattermost#6156)

* Improve support for building the docs on Windows by adding more targets to make.bat and adding Windows support to the Makefile; Update README.md with more instruction for Windows platforms

* Remove redundant reference to Windows in build instructions

Author: neflyte

Makefile

@@ -13,7 +13,11 @@ SPHINXAUTOBUILD ?= pipenv run sphinx-autobuild
 
 # Put it first so that "make" without argument is like "make help".
 help:
+ifeq ($(OS),Windows_NT)
+	@CMD /C $(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+else
 	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+endif
 
 # Install necessary dependencies for the CI build pipeline.
 # NOTE: if the version of Python used to build the docs changes, update the `pipenv` command below accordingly.
@@ -26,25 +30,46 @@ test:
 
 # Run `make livehtml` to start sphinx-autobuild.
 livehtml:
+ifeq ($(OS),Windows_NT)
+	@CMD /C IF NOT EXIST $(BUILDDIR) MD $(BUILDDIR)
+	@CMD /C $(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) $(O)
+else
 	@mkdir -p "$(BUILDDIR)"
 	@$(SPHINXAUTOBUILD) "$(SOURCEDIR)" "$(BUILDDIR)/html" -d "$(BUILDDIR)/doctrees" $(SPHINXOPTS) $(O)
+endif
 
 # Run `make linkcheck` to check external links
 # Overriding `exclude_patterns` configuration to exclude
 # directories or files not included in the documentation
 linkcheck:
+ifeq ($(OS),Windows_NT)
+	@CMD /C IF NOT EXIST $(BUILDDIR) MD $(BUILDDIR)
+	@CMD /C $(SPHINXBUILD) -M $@ -D exclude_patterns=archive/*,process/* "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -w "$(WARNINGSFILE)" 2>NUL
+else
 	@mkdir -p "$(BUILDDIR)"
 	@$(SPHINXBUILD) -M $@ -D exclude_patterns=archive/*,process/* "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 2>>"$(WARNINGSFILE)"
+endif
+
 
 # Download the latest Compass Icon assets.
 compass-icons:
-	mkdir -p source/_static/css
-	mkdir -p source/_static/font
+ifeq ($(OS),Windows_NT)
+	@CMD /C IF NOT EXIST source/_static/css MD source/_static/css
+	@CMD /C IF NOT EXIST source/_static/font MD source/_static/font
+else
+	@mkdir -p source/_static/css
+	@mkdir -p source/_static/font
+endif
 	curl --no-progress-meter -o source/_static/css/compass-icons.css https://mattermost.github.io/compass-icons/css/compass-icons.css
 	curl --no-progress-meter -o "source/_static/font/compass-icons.#1" "https://mattermost.github.io/compass-icons/font/compass-icons.{eot,woff2,woff,ttf,svg}"
 
 # Catch-all target: route all unknown targets to Sphinx using the new
 # "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
+ifeq ($(OS),Windows_NT)
+	@CMD /C IF NOT EXIST $(BUILDDIR) MD $(BUILDDIR)
+	@CMD /C $(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) -w "$(WARNINGSFILE)" 2>NUL
+else
 	@mkdir -p "$(BUILDDIR)"
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) 2>>"$(WARNINGSFILE)"
+endif

README.md

@@ -57,30 +57,39 @@ Once the review process is complete, and depending on the type of issue it is (e
 
 ## Build locally
 
-If you've downloaded the `mattermost/docs` repository and are editing Mattermost documentation on your local machine, you can generate the HTML files from markdown in the `/source` directory. You can review your changes before you commit them or create pull requests.
+If you've downloaded the `mattermost/docs` repository and are editing Mattermost documentation on your local machine, you can generate the HTML files from markdown in the `source` directory. You can review your changes before you commit them or create pull requests.
 
-**Note:** Terminal commands can be executed on Linux, Mac, and Windows (using Powershell).
+**Note:** Terminal commands can be executed on Linux, Mac, and Windows (using PowerShell).
+
+### Build prerequisites
+
+The following software is required to build the documentation:
+
+- Git [[download]](https://git-scm.com/downloads)
+- Python 3.9 or later [[download]](https://www.python.org/downloads/)
+
+### Build instructions
 
 1. Open a terminal window, then clone a forked copy of the documentation repository:
-    ```sh
+    ```shell
     git clone https://github.com/mattermost/docs.git
     ```
 
 2. In the terminal window, navigate into the cloned repository:
-    ```sh
+    ```shell
     cd docs
     ```
 
 3. Install [pipenv](https://docs.pipenv.org/) by using one of the following commands based on your operating system:
 
     For Mac users where Homebrew is installed:
     ```shell
-    brew install pipenv  
+    brew install pipenv
     ```
 
     For other operating systems:
     ```shell
-    pip install --user pipenv 
+    pip install --user pipenv
     ```
 
 4. Install required Python packages:
@@ -94,10 +103,15 @@ If you've downloaded the `mattermost/docs` repository and are editing Mattermost
     - Use `make clean html` to delete all static HTML output in the `/build` directory and re-build all files. This command is particularly useful when you're making changes to the LHS navigation pane and want to ensure you're not reviewing cached results.
     - Use `make livehtml` to review a live preview published to `http://127.0.0.1:8000` that automatically updates as new changes are saved in your local IDE.
 
-6. When working with static build results, navigate to the `/build` directory:
+   Windows users will require [GNU Make](https://gnuwin32.sourceforge.net/packages/make.htm) installed for the above commands to work correctly. If GNU Make is not installed, please substitute `CMD /C make.bat` for `make` in the above commands to use the Windows command interpreter. For example `make html` will become `CMD /C make.bat html`.
+
+   Note: When using the `CMD /C make.bat` substitution, only a single target may be specified. Instead of running `CMD /C make.bat clean html`, each target must be run seperately. For example, `CMD /C make.bat clean` followed by `CMD /C make.bat html`. 
+
+6. When working with static build results, navigate to the `build` directory:
     ```sh
-    cd /build
+    cd build
     ```
-7. Then, preview your changes by opening the `/source/html/index.html` file.
+   
+7. Then, preview your changes by opening the `source/html/index.html` file.
 
-Build errors are written to the `/build/warning.log`. 
+Build errors are written to the `build/warnings.log` file. 

make.bat

@@ -13,12 +13,15 @@ if "%SPHINXAUTOBUILD%" == "" (
 set SOURCEDIR=source
 set BUILDDIR=build
 set WARNINGSFILE=%BUILDDIR%/warnings.log
-set ERRORSFILE=%BUILDDIR%/errors.log
-if not "%SPHINXOPTS%" == "" (
-    set SPHINXOPTS=-j auto -w %WARNINGSFILE%
+if "%SPHINXOPTS%" == "" (
+    set SPHINXOPTS=-j auto
 )
 
 if "%1" == "" goto help
+if "%1" == "livehtml" goto livehtml
+if "%1" == "linkcheck" goto linkcheck
+if "%1" == "test" goto test
+if "%1" == "compass-icons" goto compassicons
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -33,13 +36,29 @@ if errorlevel 9009 (
 	exit /b 1
 )
 
-md %BUILDDIR%
-%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% 2>%ERRORSFILE%
+if not exist %BUILDDIR% md %BUILDDIR%
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% -w "%WARNINGSFILE% 2>NUL
 goto end
 
 :livehtml
-md %BUILDDIR%
-%SPHINXAUTOBUILD% %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+if not exist %BUILDDIR% md %BUILDDIR%
+%SPHINXAUTOBUILD% %SOURCEDIR% %BUILDDIR%/html -d %BUILDDIR%/doctrees %SPHINXOPTS% %O%
+goto end
+
+:linkcheck
+if not exist %BUILDDIR% md %BUILDDIR%
+%SPHINXBUILD% -M linkcheck -D exclude_patterns=archive/*,process/* %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:test
+pipenv run pytest
+goto end
+
+:compassicons
+IF NOT EXIST source/_static/css MD source/_static/css
+IF NOT EXIST source/_static/font MD source/_static/font
+curl --no-progress-meter -o source/_static/css/compass-icons.css https://mattermost.github.io/compass-icons/css/compass-icons.css
+curl --no-progress-meter -o "source/_static/font/compass-icons.#1" "https://mattermost.github.io/compass-icons/font/compass-icons.{eot,woff2,woff,ttf,svg}"
 goto end
 
 :help