new web section on pixi install; more work on installation docs planned

Author: briantoby

MDhelp/docs/commontreeitems.md

@@ -210,6 +210,7 @@ Subsequent lines should contain:
    Note that quantity ``"Weight factor" * (obs-calc) / esd`` determines the impact of the restraint, 
    so the esd values are on an arbitrary scale. 
 
+If the columns are reorganized and the header changed to match, the code should be able to change to match, but this has not been tested. 
 Spacing between columns does not matter and columns do not need to be aligned. 
 With a file such as the one below, that contains both distances and angles, the file must be 
 read in twice, using the **Add MOGUL restraints** menu command from both the Bond tab and 

webdocs/install.rst

@@ -25,7 +25,15 @@ For Windows download file https://github.com/AdvancedPhotonSource/GSAS-II-buildt
 After the installer is started 
 You will have a choice for where to install the software (the default is usually OK, but something like ``c:\software`` might be better, if your computer security allows that.)
 
-More complete installation instructions `are here <install-g2f-win.html>`_.
+More complete installation instructions on the GSAS2MAIN
+installation process on windows are linked below. 
+
+.. index:: gsas2main windows details
+.. toctree::
+   :maxdepth: 1
+	      
+   install-g2f-win.rst
+
 
 MacOS
 --------------------
@@ -47,7 +55,14 @@ where:
 
  <install-loc> is where you want to install the software. (Use of ``~/g2main``, a subdirectory named ``g2main`` in your home directory is a good choice.) After installation is complete, you will be given a chance to place a shortcut for GSAS-II into the MacOS dock.
 
-More complete installation instructions are provided for `MacOS separately <install-g2f-mac.html>`_.
+More complete installation instructions on the GSAS2MAIN
+installation process on MacOS are linked below. 
+
+.. index:: gsas2main MacOS details
+.. toctree::
+   :maxdepth: 3
+	      
+   install-g2f-mac.rst
 
 Linux
 --------------------
@@ -63,6 +78,19 @@ former is built on an APS Redhat Enterprise server, while the latter
 is built on an Ubuntu GitHub runner (24.04.2 LTS, last I
 checked). Neither may be compatible with other Linux versions. 
 
+Binary compatibility between Linux systems is not all that
+good. If the above do not work, or if you prefer to use code packages
+distributed for your Linux platform, you are encouraged to use
+apt-get, yum,... to install Python (see the
+`GSAS-II Python package requirements
+<https://gsas-ii.readthedocs.io/en/latest/packages.html#gui-requirements>`_,
+and then use the ``gitcompile.py`` routine, discussed in the
+:ref:`gitcompile` section below to download, compile and install  GSAS-II. 
+Another easy-to-use option is to use pixi, (see :ref:`pixi
+installation`). The disadvantage of pixi, at least with the standard
+install, is that you will need to
+update GSAS-II manually with git commands and then rerun pixi.
+
 To install GSAS2MAIN in Linux using the GitHub runner  version, use a command such as::
   
   g2="https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/download/v1.0.1/gsas2main-Latest-Linux-x86_64.sh"
@@ -78,51 +106,34 @@ where:
 
  <install-loc> is where you want to install the software. (Use of
  ``~/g2main``, a subdirectory named ``g2main`` in your home directory
- is a good choice.) More details on use of the `GSAS2MAIN installer on
- Linux is here <install-g2f-linux.html>`_.
+ is a good choice.)
 
-As note above, binary compatibility between Linux systems is not all that
-good. If the above do not work, or if you prefer to use code packages
-distributed for your Linux platform, you are encouraged to use
-apt-get, yum,... to install Python (see the
-`GSAS-II Python package requirements
-<https://gsas-ii.readthedocs.io/en/latest/packages.html#gui-requirements>`_,
-and then use the ``gitcompile.py`` routine, discussed in the
-:ref:`gitcompile` section below to download, compile and install  GSAS-II. 
-Another easy-to-use option is to use pixi, (see :ref:`pixi
-installation`). The disadvantage of pixi is that you will need to
-update GSAS-II manually with git commands and then rerun pixi.
-
-GSAS2MAIN Additional Details
-----------------------------------------
-
-The pages listed below go through the GSAS2MAIN installation process on each identified platform in much greater detail.
+More complete installation instructions on the GSAS2MAIN
+installation process on linux are below. 
 
-.. index:: gsas2pkg installer
+.. index:: gsas2main MacOS details
 .. toctree::
    :maxdepth: 3
 
-   install-g2f-win.rst
-   install-g2f-mac.rst
    install-g2f-linux.rst
-	      
-
-GSAS2PKG Conda Package
-=======================
 
-Users who work extensively with Python and use the conda Python installer may prefer to utilize their existing conda installation to obtain GSAS-II along with the Python configuration that GSAS-II prefers. This can be done with this command (on all platforms)::
-
-  conda create -n GSASII briantoby::gsas2pkg  -c conda-forge
-
-This creates a conda virtual environment named ``GSASII`` (this can be changed) for use by GSAS-II. While it is also possible to install GSAS-II into the conda base environment, this is not recommended as it can create conflicts between Python and package versions needed by GSAS-II and those required by other packages. (If you choose to do this anyway, be sure to specify ``conda install python=3.13 briantoby::gsas2pkg`` as Python is likely to be pinned to a different version.)
-
-After this command is run, use command ``conda activate GSASII`` to access the
-conda environment that has been created. On Linux and MacOS computers, two shortcut commands will then be available in the path, The first command, ``gsasII.sh``, which will start GSAS-II. This can optionally be used as ``gsasII.sh project.gpx`` to open existing project file ``project.gpx`` in GSAS-II. The second command, ``reset-gsasII.sh``  will rarely be used. This command will download the latest version of GSAS-II and update to that version, replacing any locally modified files with the original versions. This can be used to update GSAS-II when the program will not start, so the normal Help->Update menu command cannot be accessed. (Shortcuts available with gsas2pkg v5.1+.)
+Installing GSAS-II via pixi
+======================================================
 
-Note that on MacOS, a Mac app is also created and is displayed in the Finder
-`see steps 5 & 6 here <install.html#macos-gsas2main-installation-details>`_. This app can be used to start GSAS-II from the dock or desktop.
+Due to royalty issues with use of Anaconda, Inc. conda packages (which
+GSAS-II does not use; GSAS-II only uses conda-forge which is
+non-proprietary), some sites are encouraging use of pixi rather than
+conda. The pixi installer can be used directly after downloading
+GSAS-II from the GitHub site. It installs Python and all packages
+needed for GSAS-II and it also compiles GSAS-II locally, rather than
+downloading pre-built binaries, which is of particular value for
+Linux. It interferes with GSAS-II's self-updating process, however. 
 
-.. index:: Installing GSAS-II with gitstrap.py
+.. index:: pixi installation
+.. toctree::
+   :maxdepth: 3
+	      
+   install_pixi.rst
 
 Installing GSAS-II with a Separate Python Installation
 ======================================================
@@ -238,11 +249,35 @@ start due to changes that have been made locally, the ``--reset``
 option might be needed.
 
 .. index:: Installing GSAS-II from GitHub
+
+
+GSAS2PKG Conda Package
+=======================
+
+Users who work extensively with Python and use the conda Python installer may prefer to utilize their existing conda installation to obtain GSAS-II along with the Python configuration that GSAS-II prefers. This can be done with this command (on all platforms)::
+
+  conda create -n GSASII briantoby::gsas2pkg  -c conda-forge
+
+This creates a conda virtual environment named ``GSASII`` (this can be changed) for use by GSAS-II. While it is also possible to install GSAS-II into the conda base environment, this is not recommended as it can create conflicts between Python and package versions needed by GSAS-II and those required by other packages. (If you choose to do this anyway, be sure to specify ``conda install python=3.13 briantoby::gsas2pkg`` as Python is likely to be pinned to a different version.)
+
+After this command is run, use command ``conda activate GSASII`` to access the
+conda environment that has been created. On Linux and MacOS computers, two shortcut commands will then be available in the path, The first command, ``gsasII.sh``, which will start GSAS-II. This can optionally be used as ``gsasII.sh project.gpx`` to open existing project file ``project.gpx`` in GSAS-II. The second command, ``reset-gsasII.sh``  will rarely be used. This command will download the latest version of GSAS-II and update to that version, replacing any locally modified files with the original versions. This can be used to update GSAS-II when the program will not start, so the normal Help->Update menu command cannot be accessed. (Shortcuts available with gsas2pkg v5.1+.)
+
+Note that on MacOS, a Mac app is also created and is displayed in the Finder
+`see steps 5 & 6 here <install.html#macos-gsas2main-installation-details>`_. This app can be used to start GSAS-II from the dock or desktop.
+
+.. index:: Installing GSAS-II with gitstrap.py
+
 
 Installation Info for Developers
 ==============================================
 
-While all of the above approaches will clone a copy of the GSAS-II repository from GitHub, software developers may find it more convenient to clone the repo themselves. This will typically be done as part of a process where a copy of GSAS-II is forked on GitHub. This is described in a `separate page <install_dev.html>`_ (outline below). 
+While all of the above approaches will clone a copy of the GSAS-II
+repository from GitHub, software developers may find it more
+convenient to clone the repo themselves. This will typically be done
+as part of a process where a copy of GSAS-II is forked on GitHub. This
+is described in a `separate page <install_dev.html>`_ (outline
+below). 
 
 .. index:: Installing for development
 .. toctree::
@@ -251,20 +286,6 @@ While all of the above approaches will clone a copy of the GSAS-II repository fr
    install_dev.rst
 
 
-Older Installers
-=================================
-
-Previously GSAS-II was provided via an Advanced Photon Source-maintained subversion (svn) server, with differing installation processes. The subversion server is not longer being updated, so those installers should not be used because if GSAS-II is installed from subversion, you will not be able to update to the current GSAS-II version.
-If you previously installed GSAS-II from that server, you will be
-shown a message when trying to update that you should reinstall
-GSAS-II as described above.
-
-Likewise, the gsas2full installer was used to install GSAS-II from the
-older ``master`` branch. Use of this installer is discouraged. If you
-install GSAS-II from that branch, you will be
-be offered the opportunity to add needed Python packages and switch to
-the ``main`` branch when trying to update GSAS-II from the help menu.
-
 Installation Details
 ====================================
 
@@ -280,3 +301,16 @@ if the distributed binaries cannot be used.
    install-pip.rst
    proxy.rst
 
+Older Installers
+=================================
+
+Previously GSAS-II was provided via an Advanced Photon Source-maintained subversion (svn) server, with differing installation processes. The subversion server is not longer being updated, so those installers should not be used because if GSAS-II is installed from subversion, you will not be able to update to the current GSAS-II version.
+If you previously installed GSAS-II from that server, you will be
+shown a message when trying to update that you should reinstall
+GSAS-II as described above.
+
+Likewise, the gsas2full installer was used to install GSAS-II from the
+older ``master`` branch. Use of this installer is discouraged. If you
+install GSAS-II from that branch, you will be
+be offered the opportunity to add needed Python packages and switch to
+the ``main`` branch when trying to update GSAS-II from the help menu.

webdocs/install_dev.rst

@@ -128,80 +128,3 @@ You are strongly encouraged to create a separate branch for each development pro
 
 When your changes are complete and you are ready to communicate them back, you will commit them locally and use ``git push`` to upload them to GitHub. From the web interface to GitHub you can then submit that branch as a pull request to the main GSAS-II repository. Once you have submiited your pull request, you likely will want to switch to a different branch to do any further development work, as if changes are uploaded for the branch used for the pull request, those changes will be added to the code in the pull request.
 
-.. index:: Installing with pixi
-
-.. _pixi installation:
-   
-==============================================
- Using Pixi to install GSAS-II
-==============================================
-
-The code in the ``main`` includes setup files for `Pixi <https://pixi.sh>`_, which is a package management tool for developers.  If one uses Git to install the GSAS-II files and installs the Pixi software, GSAS-II can be configured and installed very simply.
-It is particularly convenient for GSAS-II software development. 
-There are many ways to install Pixi, as listed `here <https://pixi.sh>`_, or by using the ``conda install pixi`` command, or homebrew, etc. 
-
-Once pixi is installed, it can be used to setup and run GSAS-II, with commands as described below. These commands download GSAS-II from GitHub, install it, including compiling the files locally, then runs the self-tests and then finally starts the GSAS-II GUI:: 
-
-        cd <install-location>
-        git clone --depth 1 [email protected]:AdvancedPhotonSource/GSAS-II.git
-        cd GSAS-II/pixi
-        pixi run install
-        pixi run test
-        pixi run ui
-
-The pixi program makes all this very easy. Developers will likely want to clone from their own fork of the repo (see above) and may want to use variants on these commands, such as add `--no-single-branch` so that all branches are available and/or change the `--depth` value or even omit that option.  (Any of these increase the download time significantly.)
-Also note the `install-editable` or `install-editable-win` options below. This allows that git-installed code is used to run GSAS-II rather than copies. With this "`editable" option you can make changes to GSAS-II and then restart it and see the impact of your changes immediately [with a bit of tampering, sometimes one can use `importlib.reload()` and see changes as soon as they are saved]. If the normal install process is used, the changes will be seen only after repeating the `pixi run install` step.
-
----------------------------------------------------
-GSAS-II pixi commands
----------------------------------------------------
-
-Details on commonly-used commands with pixi follow: 
-
-``pixi run install``
-
-     This will install GSAS-II into the ``pixi/.pixi`` directory where it will be
-     used by exclusively by pixi. The GSAS-II Fortran, etc. files will be compiled
-     and will be placed with other executable files used by Python.
-
-``pixi run install-editable`` (Linux/MacOS)
-
-``pixi run install-editable-win`` (on Windows)
-     
-     This will set up to run GSAS-II in the directory where the files are originally
-     located. This is ideal for code development as changes in Python code will
-     immediately be seen as soon as GSAS-II is restarted and git commands can
-     be used to upload changes to GitHub. Note the slightly different version of
-     this command for Windows.
-
-After one of the above install commands is used, the following commands can be used:
-
-``pixi run test``
-
-    Runs the GSAS-II self-test suite (takes 1-2 minutes typically to complete.)
-    See :ref:`example output here<example_pytest_output>`.
-
-``pixi run ui``
-
-    Starts the GSAS-II GUI. 
-
-``pixi run python``
-
-    Starts Python with the GSAS-II environment established. 
-
-``pixi shell``
-
-    Starts a shell (bash, cmd.exe,...) where conda, python, etc. are available to run.
-    The GSAS-II environment is setup. This is a useful command for developing
-    or running GSASIIscriptable scripts. 
-
----------------------------------------------------
-Use of non-default pixi environments
----------------------------------------------------
-
-By default, the commands above will install and run GSAS-II with Python 3.13 (at the time this is written), but pixi can also setup GSAS-II to run with alternate Python versions. Available options are ``py310``, ``py311``, and ``py312``. To use an alternate environment, it should be added to every command, such as
-``pixi run -e py311 install-editable-win``, 
-``pixi run -e py311 test``, 
-``pixi run -e py311 ui`` or 
-``pixi shell -e py311``.
-