doc: extend --enable-set-pythonpath documentation

Signed-off-by: Xavier Delaruelle <xavier.delaruelle@cea.fr>

Author: xdelaruelle

.hunspell.en.dic

@@ -1339,3 +1339,5 @@ OSX
 BAWT
 HTTPS
 mirrorEnvVarChange
+PYTHONPATH
+pythonpath

NEWS.rst

@@ -111,6 +111,21 @@ Modules 5.7.0 (not yet released)
 * Also consider ``-`` in addition to ``.`` as a version number separator
   character when selecting a module with the :mconfig:`extended_default`
   mechanism. (fix issue #619)
+* Rename Modules initialization script for Python ``env_modules.py`` to make
+  it a proper Python module name.
+* Rename the Python initialization script to :file:`env_modules.py` so that it
+  uses a valid Python module name. Generates a :file:`python.py` symlink onto
+  :file:`env_modules.py` to preserve compatibility. (contribution from Byron
+  Boulton)
+* Install: introduce the :instopt:`--enable-set-pythonpath` installation
+  option to prepend Modules ``init`` directory to the :envvar:`PYTHONPATH`
+  environment variable during Modules initialization. This option is enabled
+  by default and make it easier to import the ``env_modules`` Python module.
+  (fix issue #483 with contribution from Byron Boulton)
+* Install: add the :instopt:`--enable-append-pythonpath` installation option,
+  which causes :instopt:`--enable-set-pythonpath` to append the Modules
+  ``init`` directory to :envvar:`PYTHONPATH` instead of prepending it.
+  (contribution from Byron Boulton)
 
 
 .. _5.6 release notes:

doc/source/changes.rst

@@ -1010,6 +1010,10 @@ The following module sub-commands appeared on Modules 5.
  Starting Modules 5.5, definition of :command:`mogui` shell alias or function
  is added on this sub-command.
 
+ Starting Modules 5.7, initialization directory is added to ``PYTHONPATH``
+ environment variable unless installation option
+ :instopt:`--disable-set-pythonpath<--enable-set-pythonpath>` is used.
+
 :subcmd:`lint`
 
  Starting Modules 5.6, readable modulecache files are also linted when no

doc/source/module.rst

@@ -89,11 +89,18 @@ time if :command:`mogui-cmd` command is found in :envvar:`PATH`.
 changes performed in the GUI is applied onto the shell session that executed
 :command:`mogui`.
 
+The installation location of the ``env_modules`` Python module may also be
+added to the :envvar:`PYTHONPATH` environment variable during initialization,
+unless the :instopt:`--enable-append-pythonpath` installation option has been
+disabled.
+
 .. only:: html or latex
 
    .. versionchanged:: 5.5
       Definition of :command:`mogui` alias or function added
 
+   .. versionchanged:: 5.7
+      Update of :envvar:`PYTHONPATH` environment variable added
 
 Examples of initialization
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -128,14 +135,13 @@ Perl:
 
 Python:
 
-Default installation should have added |file initdir| to the :envvar:`PYTHONPATH` environment variable allowing initialization as follows
-
 .. parsed-literal::
 
      from env_modules import module
      module("load", "modulefile", "modulefile", "...")
 
-Otherwise
+Alternative initialization for Python if ``env_modules`` script is not part of
+an enabled Python module directory:
 
 .. parsed-literal::