diff --git a/doc/changes/latest.inc b/doc/changes/latest.inc index 65525514cf1..736d4f7c242 100644 --- a/doc/changes/latest.inc +++ b/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 ~~~ diff --git a/doc/conf.py b/doc/conf.py index 6046bb6af42..8e641a08a64 100644 --- a/doc/conf.py +++ b/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_',), diff --git a/doc/install/contributing.rst b/doc/install/contributing.rst index 2c76f55dafd..d4e0410c254 100644 --- a/doc/install/contributing.rst +++ b/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={} + 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 diff --git a/doc/sphinxext/gen_commands.py b/doc/sphinxext/gen_commands.py index ad24952040f..eda53fed6e2 100644 --- a/doc/sphinxext/gen_commands.py +++ b/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]