revise for master2main

Author: briantoby

webdocs/developers.rst

@@ -21,6 +21,10 @@ against the latest distribution. See the web page on
 `Installing GSAS-II for code development <install_dev.html>`_ for more
 details. 
 
+---------------------------------------------------------- 
+Developer's documentation
+----------------------------------------------------------
+
 The Sphinx documentation for the GSAS-II source code will be of
 significant value for people attempting to work their way through the
 codebase. This is found on the wonderful “Read The Docs” web
@@ -39,3 +43,26 @@ the command for this is::
 
 More on this is in the `Installing GSAS-II for code development <install_dev.html>`_ 
 web page, which discusses changing the origin to your forked copy of GSAS-II.
+
+---------------------------------------------------------- 
+Developing GSAS-II inside VSCode
+----------------------------------------------------------
+
+Visual Studio Code (VSCode) is a free code development environment that is available on all major platforms where GSAS-II runs. Yuanpeng Zhang (ORNL) has written some notes on how to
+`make GSAS-II run in the VSCode debugger <https://iris2020.net/2025-04-21-gsasii_dev_new/>`_.
+
+Note that if you have used the gsas2main installer to place GSAS-II at ``~/g2main`` then you can use the Python installation there (examples:
+Mac/Linux, ``/Users/toby/G2/g2main/bin/python``;
+Windows, ``c:\Users\toby\g2main\python.exe``)
+to run the debugger rather than install a new conda environment as he does. 
+
+---------------------------------------------------------- 
+IPython Code development tip
+---------------------------------------------------------- 
+   
+One nice trick for working with GSAS-II is that if you locate a place where you want to insert code into the program, you can run commands in that environment. To do this, two prerequisite steps are needed. First, use the conda command to install iPython (this assumes you have already used the activate command, as above)::
+
+    conda install ipython
+
+Then run GSAS-II and use the Preferences command (File menu or on MacOs on the first menu, named GSAS-II or python) and `set the debug option to True`. One can then place a
+``breakpoint()`` statement into GSAS-II at a location where one wants to develop code. When that statement is executed, GSAS-II will enter iPython but in the local environment where your code will be executed, so you can see what variables and functions are defined and try running code that can then be placed into GSAS-II. Remember to remove the breakpoint statement when you are done. 

webdocs/index.rst

@@ -9,6 +9,18 @@
 GSAS-II Home Page
 ====================================
 
+.. tip::
+
+   As of April 22, 2025, the default branch for GSAS-II has been
+   changed from ``master`` to a branch called ``main``. If the
+   gsas2full self-installer was used for GSAS-II use of the
+   Help/Update process should make the transition from the ``master``
+   to the new ``main`` version. Other types of installations will
+   likely require that GSAS-II be reinstalled (as described
+   below). Details about what has been changed in this transition can
+   be found in the :ref:`section on this transition <master2main>`,
+   also below. 
+
 Welcome to the home page for GSAS-II, a unique and comprehensive open
 source Python project for determination of crystal structures and
 diffraction-based materials characterization for crystalline solids on
@@ -33,6 +45,7 @@ well as extensive visualization capabilities.
    developers.rst 
    compile.rst 
    misc.rst 
+   master2main.rst 
 
 .. tip::
     Please help us by citing:
@@ -150,4 +163,8 @@ Other things related to GSAS-II can be found here.
 
 .. toctree::
 
-   misc.rst 
+   misc.rst
+   
+.. toctree::
+
+   master2main.rst 

webdocs/install_dev.rst

@@ -207,26 +207,3 @@ By default, the commands above will install and run GSAS-II with Python 3.13 (at
 ``pixi run -e py311 ui`` or 
 ``pixi shell -e py311``.
 
-
-==============================================
- Developing GSAS-II inside VSCode
-==============================================
-
-Visual Studio Code (VSCode) is a free code development environment that is available on all major platforms where GSAS-II runs. Yuanpeng Zhang (ORNL) has written some notes on how to
-`make GSAS-II run in the VSCode debugger <https://iris2020.net/2025-04-21-gsasii_dev_new/>`_.
-
-Note that if you have used the gsas2main installer to place GSAS-II at ``~/g2main`` then you can use the Python installation there (examples:
-Mac/Linux, ``/Users/toby/G2/g2main/bin/python``;
-Windows, ``c:\Users\toby\g2main\python.exe``)
-to run the debugger rather than install a new conda environment as he does. 
-
-==============================================
-IPython Code development tip
-==============================================
-   
-One nice trick for working with GSAS-II is that if you locate a place where you want to insert code into the program, you can run commands in that environment. To do this, two prerequisite steps are needed. First, use the conda command to install iPython (this assumes you have already used the activate command, as above)::
-
-    conda install ipython
-
-Then run GSAS-II and use the Preferences command (File menu or on MacOs on the first menu, named GSAS-II or python) and `set the debug option to True`. One can then place a
-``breakpoint()`` statement into GSAS-II at a location where one wants to develop code. When that statement is executed, GSAS-II will enter iPython but in the local environment where your code will be executed, so you can see what variables and functions are defined and try running code that can then be placed into GSAS-II. Remember to remove the breakpoint statement when you are done. 

webdocs/master2main.rst

@@ -0,0 +1,37 @@
+April 2025: Transition from Master to Main Branch
+==================================================
+
+.. _master2main:
+
+On April 22, 2025 GSAS-II made a transition from development on a branch named "master" to a branch named "main". Several months of changes are behind this transition, which is documented below.
+
+* Meson for building: Prior to this transition, the scons utility had been used to compile GSAS-II source code (written in Fortran, cython and C) into binaries. This broke with Python 3.12. A new compilation mechanism based on meson was implemented. The initial work on this was done by Jerome Kieffer (ESRF) and additional help was obtained from Tom Caswell (NSLS-II/BNL). GSAS-II is now provided with Python 3.12 and 3.13 binaries.
+
+* Rework of self-installers: The GSAS-II self-installer, previously called gsas2full and now renamed as gsas2main, was revisited and streamlined. There is also now a conda package, also named gsas2main (on channel briantoby), but this is intended only for internal use in the self-installer.
+
+* self-tests: there is now a suite of scripts that test the GSAS-II compiled binaries as well as significant portions of the GSAS-II crystallographic computations. These are run automatically when changes are checked into the main branch. They are also used to test binaries created with meson and are used to test self-installers (gsas2main).
+
+* GitHub actions: there are a series of scripts for `the source code repository< https://github.com/AdvancedPhotonSource/GSAS-II/actions>`_
+and  for `the build repository<https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/actions>`_ for these tasks:
+  
+  (1) Run the self-tests (smoke test, ``smoke_test.yml``). This is run whenever there are code check-ins to main. 
+  (2) Create and test self-installers (build & test self-installers, ``matrix_g2main-test.yml``). At present this is triggered manually.
+  (3) Compile GSAS-II binaries (compile & test binaries, ``matrix_comp-test.yml``). At present this is triggered manually.
+  (4) Create and test a self-installer for RHEL (Build & test (RHEL) gsas2main self-installer, ``g2main-redhat.yml``). At present this is triggered manually.
+  (5) Build the GSAS-II conda package, (build gsas2pkg, ``gsas2pkg.yml``). Work on this is not yet complete.
+
+* Internal file reorganization: The GSAS-II Python files have been reorganized so that GSAS-II can be installed into Python's normal installation location (site-packages) and so that routines can be accessed using ``import GSASII`` (or ``import GSASII.G2-module``). This required revision of internal imports from ``import GSASIIobj as G2obj`` to ``from . import GSASIIobj as G2obj`` (or ``from .. import...`` in the ``imports`` and ``exports`` subdirectories.) Tom Caswell (NSLS-II/BNL) did much of this. 
+
+* External packages previously included in GSAS-II (PyCifRW and baselines) are now installed as Python packages
+  
+* A new "update" routine has be included in master that installs newly required Python packages (such as PyCifRW and baselines) and then switches branches and reinstalls shortcuts. This is called when one attempts to update the "master" branch once the last update to that branch has been installed.
+
+* A file named ``GSASII.py`` was previously used to start the GUI. Having a file sharing a name with a package does not work, so that file was renamed as ``GSASIIGUI.py`` and a new file named ``G2.py`` is now used to start GSAS-II.
+
+* Citations to software used in GSAS-II is now tracked in a centralized location and a new Help command provides a list of those references.
+
+* The configuration settings, which were previously saved in a Python source file, ``config.py`` are now saved in a file named ``config.ini``. That file is located in a "user" area (``~/.GSASII``) rather than with the GSAS-II source code. When the new "main" version of GSAS-II is started, if no ``config.ini`` file is found then the contents of ``config.py`` is used to initialize ``config.ini``.
+
+* Obsolete code removed. This includes the code previously used for subversion (svn).
+
+* Scripting: several commands now can read input files supplied as a URL; preferred orientation correction now are available in the API.