Skip to content

Commit

Permalink
document config options, reorg web page some
Browse files Browse the repository at this point in the history
  • Loading branch information
@briantoby
briantoby committed Oct 12, 2024
1 parent def6b2b commit dd03d6c
Show file tree
Hide file tree
Showing 3 changed files with 58 additions and 90 deletions.
2 changes: 1 addition & 1 deletion webdocs/developers.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
:align: right

====================================
Information for GSAS-II Developers
Documentation for GSAS-II Developers
====================================

Note the `documentation web page <documentation.html>`_, as the
Expand Down
118 changes: 36 additions & 82 deletions webdocs/index.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,32 +9,31 @@
GSAS-II Home Page
====================================

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
all scales, from perovskites through proteins, using both powder and
single-crystal diffraction and with both x-ray and neutron
probes. Refinements can combine measurements from laboratory and
synchrotron x-rays, as well as constant wavelength or time-of-flight
neutron sources. It provides structure solution and refinement, as
well as extensive visualization capabilities.

.. toctree::
:caption: Contents
:caption: Home Page Contents
:maxdepth: 1
:numbered:

install.rst
documentation.rst
help.rst
mailinglist.rst
bug.rst
developers.rst
compile.rst
install-pip.rst
proxy.rst

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
all scales, from perovskites through proteins, using both powder and
single-crystal diffraction and with both x-ray and neutron
probes. Refinements can combine measurements from laboratory and
synchrotron x-rays, as well as constant wavelength or time-of-flight
neutron sources. It provides structure solution and refinement, as
well as extensive visualization capabilities.

GSAS-II is made available for free use (`see license <https://raw.githubusercontent.com/AdvancedPhotonSource/GSAS-II/master/LICENSE>`_) with open access to the `source code <https://github.com/AdvancedPhotonSource/GSAS-II>`_.

.. tip::
Please help us by citing:

Expand All @@ -46,6 +45,8 @@ GSAS-II is made available for free use (`see license <https://raw.githubusercont
codes or reference later work, with citations provided
as they are used. *Please* cite them as well.

GSAS-II is made available for free use (`see license <https://raw.githubusercontent.com/AdvancedPhotonSource/GSAS-II/master/LICENSE>`_) with open access to the `source code <https://github.com/AdvancedPhotonSource/GSAS-II>`_.

Also, please do sign up for the GSAS-II mailing list `see below <mailinglist.html>`_.
We add new features to GSAS-II quite frequently, so we may break
things from time to time (`see bug reporting <bug.html>`_). Be
Expand All @@ -64,7 +65,7 @@ There are several different ways to install GSAS-II, as are outlined below. Most

install.rst

Available Documentation
Documentation for Users
====================================

While there is no manual for GSAS-II, there is quite a bit of
Expand All @@ -77,62 +78,15 @@ web-based documentation, as listed below.
Help: GSAS-II will not start
====================================

While I hope this never happens again, there have been occasions where a
version of GSAS-II has a bug that prevents the program from starting.
If this version is installed, it is then not possible to access the
Help/Update menu command to obtain the different version of
GSAS-II. The same thing can also happen if you make changes to the
files yourself and introduce an error. Also, if you make changes to
the GSAS-II Python (.py) files, you can no longer obtain updates.

A script is provided that can be used to reset any locally made
changes and then install the lastest version of GSAS-II. If you have
made changes that you wish to retain, you should make a copy of them
either using a utility to place a copy elsewhere, or you can use the
git stash, branch or commit commands. The commands below will
overwrite your changes with the latest GSAS-II version.

On windows
----------------

At present, two windows .BAT files are created in the directory where
GSAS-II is installed, one named `Reset2FreshGSASII.bat` the other
`start_G2_bootstrap.bat`. Thus, if GSAS-II is installed in directory
`C:\Users\toby\gsas2full` the files will be named
`C:\Users\toby\gsas2full\Reset2FreshGSASII.bat` and
`C:\Users\toby\gsas2full\start_G2_bootstrap.bat`.
Either will restore the GSAS-II files, but the
`Reset2FreshGSASII` file, will ask you to confirm before acting. The
files can run by locating them in the Windows File Explorer and
double-clicking on it or by typing the file name into the cmd.exe
window.

On MacOS/Linux
----------------

At the time this is being written, an error prevents the script from
running, but this can be corrected by editing the `reset-gsasII.sh`
file manually (see below). Note that this file is placed in the `bin` directory
immediately below the GSAS-II installation directory. Thus, if
GSAS-II is installed at location `/Users/toby/G2/gsas2full` then the
file will be named `/Users/toby/G2/gsas2full/bin/reset-gsasII.sh`. (It
will appear in the path if conda is initialized.) Depending on the OS,
it may be possible to locate and run this file in a system-supplied
file browser, or type the file name into a terminal window.

The error in the script is that the second line is incorrect. If the
lines appear as::

# Commands to run GSAS-II load/update process
source /bin/activate base
/Users/toby/G2/gsas2full/bin/python /Users/toby/G2/gsas2full/gitstrap.py --reset

The second line should be changed as follows::

# Commands to run GSAS-II load/update process
source /Users/toby/G2/gsas2full/bin/activate base
/Users/toby/G2/gsas2full/bin/python /Users/toby/G2/gsas2full/gitstrap.py --reset
If there is a bug in GSAS-II, check for updates (using the Help/Update
menu command) and if the bug is present in the latest version, please
report it (see section below on reporting bugs).
Should GSAS-II fail to start after an update, then there are alternate
ways to update GSAS-II, as discussed below.

.. toctree::

help.rst

Mailing List
====================================
Expand All @@ -155,26 +109,26 @@ fixed. Information on how to report bugs is here.

bug.rst


Information for code developers
Customizing GSAS-II
====================================

We encourage you to improve GSAS-II or to use the code in your own
projects. Some starting information is here:
There are many options within GSAS-II that allow you to tailor aspects
of the program to operate differently, for example to change how
powder diffraction refinement results are plotted or some defaults
used in different parts of the program.

.. toctree::

developers.rst
options.rst

Installation details

Documentation for code developers
====================================

Most people will not need these details, but some specific
installation details are discussed in the topics below.
We encourage you to improve GSAS-II or to use the code in your own
projects. Some starting information is here:

.. toctree::
:maxdepth: 3

compile.rst
install-pip.rst
proxy.rst

developers.rst

28 changes: 21 additions & 7 deletions webdocs/install.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,20 +3,20 @@
:alt: GSAS-II logo
:align: right

============================
GSAS-II Installation Options
============================
====================================
Choices for GSAS-II Installation
====================================

.. index:: Installation overview

Running GSAS-II requires a number of coordinated installation steps and there are many different ways this can be accomplished. One needs not only the necessary Python source code for GSAS-II, but a Python interpreter that includes a number of "add-on" Python packages for additonal capabilities. This much match the computer where the software will be run. Further, GSAS-II requires that a small amount of its code be compiled, typically for speed and this must be matched both the computer OS and to the Python version. Here I outline different a few different approaches.
Running GSAS-II requires a number of coordinated installation steps and there are many different ways this can be accomplished. One needs not only the necessary Python source code for GSAS-II, but a Python interpreter that includes a number of "add-on" Python packages for additional capabilities. This much match the operating system for the computer where the software will be run. Further, GSAS-II requires that a small amount of its code be compiled, typically for speed and this must be matched both the computer OS and to the Python version. Here I outline different a few different approaches.

.. index:: gsas2full installer

GSAS2FULL installer
=======================

Most users of GSAS-II are seeking a simple way to install and run the software and can live with the idea that they may have duplicated Python installations (several hundreds of MB each) on their computer. The GSAS2FULL self-installer provides that and can be `downloaded from here <https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/latest>`_. Brief installation instructions are outlined below with links to more complete instructions:
Most users of GSAS-II are seeking a simple way to install and run the software and can live with the idea that they may have duplicated Python installations (several hundreds of MB each) on their computer. The GSAS2FULL self-installer provides simple installation and can be `downloaded from here <https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/latest>`_. Brief installation instructions are outlined below with links to more complete instructions:

Windows
-----------
Expand Down Expand Up @@ -110,5 +110,19 @@ While all of the above approaches will clone a copy of the GSAS-II repository fr
Older installers
=================================

Previously GSAS-II was provided via an Advanced Photon Source-maintained subversion (svn) server, with differing installation processes. While the installers for those processes are still available, this is not encouraged. Also, while updates will be provided for those past svn installations for the immediate future, this will not be continued indefinitely. Thus, we are encouraging users to reinstall GSAS-II via one of the above methods if they previously installed GSAS-II via svn. When updates via svn will be phased out, GSAS-II will provide warning messages.

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.

Installation details
====================================

Most people will not need these details, but some specific
installation details are discussed in the topics below.

.. toctree::
:maxdepth: 3

compile.rst
install-pip.rst
proxy.rst

0 comments on commit dd03d6c

Please sign in to comment.