MRG, DOC: get docs to build on Windows (mne-tools#8057)

* get docs to build on Windows

- set encoding of "commands.rst.new" to 'utf8',
- do not use memory_profiler on Windows,
- add graphviz as a requirement and the conda command to install it,
- add optipng as a requirement with ways to install it on Linux/MacOS/Windows

* added whats_new

* added notes on setting environment variables on Windows

doc/changes/latest.inc

@@ -143,6 +143,9 @@ Changelog
 
 - Add function :func:`mne.channels.combine_channels` to combine channels from Raw, Epochs, or Evoked according to ROIs (combinations including mean, median, or standard deviation; can also use a callable) by `Johann Benerradi`_
 
+- Improved documentation building instructions and execution on Windows by `Eric Larson`_ and `kalenkovich`_
+
+
 Bug
 ~~~
 

doc/conf.py

@@ -542,7 +542,7 @@ def reset_warnings(gallery_conf, fname):
     'abort_on_example_error': False,
     'reset_modules': ('matplotlib', Resetter()),  # called w/each script
     'image_scrapers': scrapers,
-    'show_memory': True,
+    'show_memory': not sys.platform.startswith('win'),
     'line_numbers': False,  # XXX currently (0.3.dev0) messes with style
     'within_subsection_order': FileNameSortKey,
     'capture_repr': ('_repr_html_',),

doc/install/contributing.rst

@@ -184,6 +184,9 @@ contributors. First, edit these two variables for your situation::
     $ # pick where to put your local copy of MNE-Python development version:
     $ INSTALL_LOCATION="/opt"
 
+.. note::
+   On Windows, add ``set`` before the variable names (``set GITHUB_USERNAME=...``, etc.).
+
 Then make a local clone of your remote fork (``origin``)::
 
     $ cd $INSTALL_LOCATION
@@ -231,6 +234,15 @@ MNE-Python, but are needed for locally running our test suite::
 And for building our documentation::
 
     $ pip install -r requirements_doc.txt
+    $ conda install graphviz
+
+To build documentation, you will also require `optipng`_:
+
+- On Linux, use the command ``sudo apt install optipng``.
+
+- On MacOS, optipng can be installed using Homebrew.
+
+- On Windows, unzip optipng.exe from the `optipng for Windows`_ archive into the ``doc`` folder.
 
 You can also choose to install some optional linters for reStructuredText::
 
@@ -729,6 +741,14 @@ all the documentation and additionally execute just your example or tutorial
 (so you can make sure it runs successfully and generates the output / figures
 you expect).
 
+.. note::
+   On Windows, to use the pattern approach, use the following two lines:
+
+   .. code-block:: python
+
+      set PATTERN={<REGEX_TO_SELECT_MY_TUTORIAL>}
+      make html_dev-pattern
+
 After either of these commands completes, ``make show`` will open the
 locally-rendered documentation site in your browser. Additional ``make``
 recipes are available; run ``make help`` from the :file:`doc` directory or
@@ -918,3 +938,8 @@ it can serve as a useful example of what to expect from the PR review process.
 .. _travis: https://travis-ci.org/mne-tools/mne-python/branches
 .. _azure: https://dev.azure.com/mne-tools/mne-python/_build/latest?definitionId=1&branchName=master
 .. _circle: https://circleci.com/gh/mne-tools/mne-python
+
+.. optipng
+
+.. _optipng: http://optipng.sourceforge.net/
+.. _optipng for Windows: http://prdownloads.sourceforge.net/optipng/optipng-0.7.7-win32.zip?download

doc/sphinxext/gen_commands.py

@@ -66,7 +66,7 @@ def generate_commands_rst(app=None):
         for fname in glob.glob(op.join(command_path, 'mne_*.py'))])
     iterator = sphinx_compatibility.status_iterator(
         fnames, 'generating MNE command help ... ', length=len(fnames))
-    with open(out_fname, 'w') as f:
+    with open(out_fname, 'w', encoding='utf8') as f:
         f.write(header)
         for fname in iterator:
             cmd_name = fname[:-3]