update docs (#229)

* update docs for windows installation and temporary_config

* update docs for windows installation and temporary_config

* minor edit

Co-authored-by: Tom Young <39765193+t-young31@users.noreply.github.com>

doc/config.rst

@@ -82,6 +82,59 @@ basis set for optimisations:
 
 ------------
 
+Temporary configuration
+**********************
+
+It is also possible to change configuration temporarily, by using the context
+manager:
+
+.. code-block:: python
+
+    >>> ade.Config.ORCA.keywords.opt.functional
+    Functional(pbe0)
+    >>> ade.Config.n_cores = 4
+    >>> mol = ade.Molecule(smiles='CCO')
+    >>> with ade.temporary_config():
+    >>>     ade.Config.n_cores = 9
+    >>>     ade.Config.ORCA.keywords.opt.funcitonal = 'B3LYP'
+    >>>     # this calculation will run with 9 cores and B3LYP functional
+    >>>     mol.optimise(method=ade.methods.ORCA())
+    >>> # when context manager returns previous state of Config is restored
+    >>> ade.Config.n_cores
+    4
+    >>> ade.Config.ORCA.keywords.opt.functional
+    Functional(pbe0)
+
+When the context manager exits, the previous state of the configuration is
+restored.
+
+.. warning::
+    Note that the context manager works by saving the state of the Config
+    when it is called and restoring the state when it exits. The way Python
+    handles object references means that any references taken before or inside
+    the context manager will become useless after it exits. Please see the example
+    below for details.
+
+.. code-block:: python
+
+    >>> kwds = ade.Config.ORCA.keywords  # kwds refers to an object inside Config.ORCA
+    >>> with temporary_config():
+    ...     kwds.opt.functional = 'B3LYP'
+    ...     mol.optimise(method=ade.method.ORCA())
+    ...     # this works successfully
+    >>> # when context manager exits, all variables in Config are restored, including Config.ORCA
+    >>> # But kwds still refers to an object from old Config.ORCA
+    >>> kwds.opt.functional
+    Functional(B3LYP)
+    >>> ade.Config.ORCA.opt.functional  # current config
+    Functional(pbe0)
+
+As seen from the above example, the variable :code:`kwds` is useless once the
+context manager exits, and changes to :code:`kwds` no longer affects autodE. It is
+best to always modify :code:`Config` directly.
+
+------------
+
 XTB as a hmethod
 ****************
 
@@ -152,3 +205,12 @@ To log with timestamps and colours::
 
 To set the logging level permanently add the above export statements to
 your *bash_profile*.
+
+In case of Windows command prompt, use the set command to set environment
+variables::
+
+    > set AUTODE_LOG_LEVEL=INFO
+
+For powershell, use :code:`$env`::
+
+    > $env:AUTODE_LOG_FILE = 'INFO'

doc/install.rst

@@ -62,10 +62,34 @@ environment <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-e
 Git: Windows
 ------------
 
-In a bash shell within Windows Subsystem for Linux follow the steps above.
+Installing autodE on Windows from source is similar to that on Linux/Mac OS, but slightly
+more involved. A C++ compiler needs to be installed, as it is not provided by default. It is
+recommended to install Visual C/C++ compiler from `here <https://visualstudio.microsoft.com/visual-cpp-build-tools/>`_.
+Note that installing the "Build Tools for Visual Studio" and selecting only "Desktop Development with C++"
+in the installer menu is sufficient.
+
+Git is also required, this can be either installed in the form of `Git for Windows <https://git-scm.com/download/win>`_
+or in a `Conda environment <https://anaconda.org/conda-forge/git>`_. With git, first clone the autodE
+repository as shown above.
+
+Then open a Conda prompt or shell and cd to the directory where autodE has been cloned
+and then install with pip as usual ((you may want to create a new `virtual
+environment <https://conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_
+as mentioned before)::
+
+    > conda install --file requirements.txt --channel conda-forge
+    > pip install .
+
+.. note::
+    In rare cases :code:`pip` may not be able to find the Visual C/C++ compiler, despite the build
+    tools being installed and show the error message :code:`error: Microsoft Visual C++ 14.0 or greater is required`
+    . In this case, run the Visual Studio build tools command prompt, which is usually named
+    "x64 Native Tools Command Prompt for VS 2022" or something similar in the start menu (This will add compiler to
+    the PATH). Then run :code:`pip` from this command prompt.
+.. note::
+    Windows installation is also supported within Windows Subsystem for Linux (`WSL <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_).
+    Simply follow the instructions for Linux.
 
-.. warning::
-    Windows installation is only supported within Windows Subsystem for Linux (`WSL <https://docs.microsoft.com/en-us/windows/wsl/install-win10>`_)
 
 ******