work on compile section formatting

Author: briantoby

webdocs/compile.rst

@@ -45,13 +45,14 @@ branch.
 Supplied Binary Files
 ---------------------------
 
-The GSAS-II binaries are supplied on GitHub as "release" files, 
+The GSAS-II binaries are supplied on GitHub as "release" files, in
 https://github.com/AdvancedPhotonSource/GSAS-II-buildtools/releases/latest. In
-that location, the files are in tar archives named `prefix_pX.X_nY.Y.tgz`
-
-The supplied binaries are placed in a subdirectory name with name
+that location, the files are in tar archives named as
 `prefix`\ _p\ `X.X`\ _n\ `Y.Y` where
-`prefix` is noted below and `X.X` is the Python version and `Y.Y` is the numpy
+`prefix` is noted below and `X.X` is the Python version and `Y.Y` is
+the numpy version:
+
+Prefix naming:
 
   * Windows-10: 64-bit Intel-compatible processors. [Prefix `win_64_`\ ]
   * MacOS: Intel processors. [Prefix `mac_64_`\ ]
@@ -70,7 +71,7 @@ Compiling with meson for Linux/MacOS
 Compiling GSAS-II binaries is quite simple on Linux and MacOS and a
 bit more complex on Windows.
 One needs to install the
-Python meson and cython packages and a C compiler and the Gfortran
+Python meson and cython packages and a C compiler and the GFortran
 compiler.
 
 On Linux it probably best to use compilers supplied with the
@@ -94,29 +95,29 @@ steps (1) and (3), below. In that case use command::
 
     source .../g2full/bin/activate
 
-  to activate Python/conda, where `.../g2full` is the location where gsas2full was
-  installed. And in place of step (3) use command::
+to activate Python/conda, where `.../g2full` is the location where gsas2full was
+installed. And in place of step (3) use command::
 
     cd .../g2full/GSAS-II
     
-  where again `.../g2full` is the location where gsas2full was installed. 
+where again `.../g2full` is the location where gsas2full was installed. 
 
-1. Install an initial, bare-bones Python environment can be installed
+(1) Install an initial, bare-bones Python environment can be installed
 using the miniforge installer from conda-forge at
 https://github.com/conda-forge/miniforge/releases/latest. Then
 activate Python/conda as instructed by the installer (or use command::
 
        source ~/miniforge3/bin/activate
-  where `~/miniforge3` is the location where miniforge was installed.)
-  Then use the conda command to install the following packages to run GSAS-II:
+where `~/miniforge3` is the location where miniforge was installed.)
+Then use the conda command to install the following packages to run GSAS-II:
 
   python, numpy, matplotlib, scipy, wxpython, pyopengl, imageio, h5py,
   hdf5, pillow, requests, pycifrw, pybaselines, git, gitpython, conda
 
- (see `the GUI requirement section of the Developers manual 
+(see `the GUI requirement section of the Developers manual 
 <https://gsas-ii.readthedocs.io/en/latest/packages.html#gui-requirements>`_.)
 
-2. Install the Python build routines and the compilers:
+(2) Install the Python build routines and the compilers:
 
 MacOS::
 
@@ -127,6 +128,7 @@ Linux::
    sudo apt-get gcc gfortran git # or use the yum command:
    yum install gcc-gfortran git
 
+and for Linux::
    conda python numpy install meson cython -c conda-forge
 
 Note that the GSAS-II binaries will be compiled to work with a
@@ -137,26 +139,26 @@ specifying them in the conda command (such as using `python=3.13` and
 `numpy=2.2` in place of `python` and `numpy` above) to match the
 environment where GSAS-II will be run.
 
-3. Download the GSAS-II sources (if not already done) and move to the directory::
+(3) Download the GSAS-II sources (if not already done) and move to the directory::
 
    cd <...> # select where you wish to install GSAS-II
    git clone https://github.com/AdvancedPhotonSource/GSAS-II.git --depth 1 -b main G2 
    cd G2
 
-4. Create a scratch directory to compile GSAS-II into::
+(4) Create a scratch directory to compile GSAS-II into::
      
      meson setup /tmp/GSASIIc
 
-   Note that this command will fail if cython, gfortran and a c
+   Note that this command will fail if cython, GFortran and a c
    complier is not found. If the flang compiler is found, meson will
    use it, but the resulting binaries will not work properly. 
      
-5. Move to the setup directory and compile::
+(5) Move to the setup directory and compile::
      
      cd /tmp/GSASIIc
      meson compile
 
-6. There are two choices for how to install the GSAS-II binaries to
+(6) There are two choices for how to install the GSAS-II binaries to
    where they can be found by the software. If only one user will use 
    GSAS-II, use option (A), which also allows multiple GSAS-II installations to share a
    single set of binaries (should a user wish to keep multiple
@@ -184,11 +186,11 @@ environment where GSAS-II will be run.
    installed into `~/software/G2` and the binaries will be installed into
    `~/software/G2/GSASII/bin`. 
 
-7. (Optional) Clean up:
+(7) (Optional) Clean up:
 
    rm -rf /tmp/GSASIIc
 
-8. (Optional) Run Self-tests::
+(8) (Optional) Run Self-tests::
 
      conda activate base
      conda install pytest
@@ -199,7 +201,7 @@ environment where GSAS-II will be run.
   environment that was used if not base and `.../G2` here and below will be the
   location used to install GSAS-II in step (2).
 
-9. (Optional) Create shortcuts:
+(9) (Optional) Create shortcuts:
 
   Linux::
     
@@ -214,7 +216,7 @@ Compiling with meson for Windows
 
 Compiling GSAS-II binaries is bit more complex on Windows because
 separate Python environments *must* be used for compilation and
-running GSAS-II (it appears that inclusion of git and gfortran in the
+running GSAS-II (it appears that inclusion of git and GFortran in the
 same installation causes problems with accessing libraries needed by the compiler). 
 There are other ways potentially to install the tools
 needed for compilation, but use of conda will be much simpler, but
@@ -226,12 +228,12 @@ steps (1) and (2), below. In that case, use command::
 
     ...\g2full\Scripts\activate
 
-  to activate Python/conda, where `...\g2full` is the location where gsas2full was
-  installed. And in place of step (3) use command::
+to activate Python/conda, where `...\\g2full` is the location where gsas2full was
+installed. And in place of step (3) use command::
 
     cd ...\g2full\GSAS-II
     
-  where again `...\g2full` is the location where gsas2full was installed. 
+where again `...\\g2full` is the location where gsas2full was installed. 
 
 1. Install miniforge
 
@@ -242,28 +244,29 @@ steps (1) and (2), below. In that case, use command::
 
         ...\miniforge3\Scripts\activate
 
-  where `...\miniforge3` is the location where miniforge was
+  where `...\\miniforge3` is the location where miniforge was
   installed to enable the Python/conda environment. Or in the start
   menu use the "Start miniforge prompt" command which does the same
   thing.
 
-  Use this command to install the following packages to run GSAS-II:::
+  Use this command to install the following packages to run GSAS-II
+  (note this is a very long line)::
 
     conda install python numpy matplotlib wxpython pyopengl scipy git gitpython PyCifRW pillow conda requests hdf5 h5py imageio zarr xmltodict pybaselines seekpath pywin32 -c conda-forge -y
  
- (see `the GUI requirement section of the Developers manual 
-<https://gsas-ii.readthedocs.io/en/latest/packages.html#gui-requirements>`_
-for more info.)
+  (see `the GUI requirement section of the Developers manual 
+  <https://gsas-ii.readthedocs.io/en/latest/packages.html#gui-requirements>`_
+  for more info.)
 
 2. Download the GSAS-II sources (if not already done) and move to the directory::
 
-   cd <...> # select where you wish to install GSAS-II
-   git clone https://github.com/AdvancedPhotonSource/GSAS-II.git --depth 1 -b main G2 
-   cd G2
+     cd <...> # select where you wish to install GSAS-II
+     git clone https://github.com/AdvancedPhotonSource/GSAS-II.git --depth 1 -b main G2 
+     cd G2
 
 3. Install the Python build routines and the compilers. Note that this
    is done in separate environment that is located in directory
-   `..\compile` relative to GSAS-II::
+   `..\\compile` relative to GSAS-II::
      
      conda create -p ..\compile meson cython gcc gfortran python numpy -c conda-forge -y
 
@@ -290,8 +293,8 @@ for more info.)
 
      meson compile local-install
 
-   This command will copy the compiled files to `.GSASII\bin` in the
-   Home directory (usually `c:\Users\<your name>`), which
+   This command will copy the compiled files to `.GSASII\\bin` in the
+   Home directory (usually `c:\\Users\\<your name>`), which
    is appropriate for when one user will access the GSAS-II
    program.
    
@@ -301,16 +304,16 @@ for more info.)
        meson compile system-install
 
    If the first command used was `cd software` then GSAS-II was
-   installed into `software\G2` and the binaries will be installed into
-   `software\G2\GSASII\bin`. 
+   installed into `software\\G2` and the binaries will be installed into
+   `software\\G2\\GSASII\\bin`. 
 
 7. Clean up::
 
      cd ..
      rmdir /s tmp
      rmdir /s compile
 
-8. Create shortcuts:
+8. Create shortcuts::
     
     python G2\GSASII\install\makeBat.py 
 
@@ -330,7 +333,7 @@ work only with Python 3.11 or older and only with the `master`
 branch. Do not use GSAS-II will fail with Python earlier than 3.7 and may have
 some errors even with Python 3.8.
 
-The compilation process requires installation of the gcc and gfortran
+The compilation process requires installation of the gcc and GFortran
 compilers. Others will probablu not work. Also, the Python Scons
 package must be installed into Python. compilation is done with
 commands::

webdocs/index.rst

@@ -21,7 +21,7 @@ well as extensive visualization capabilities.
 
 .. toctree::
    :caption: Home Page Contents
-   :maxdepth: 1
+   :maxdepth: 1 
    :numbered:     
 
    install.rst
@@ -31,8 +31,8 @@ well as extensive visualization capabilities.
    options.rst
    help.rst 
    developers.rst 
+   compile.rst 
    misc.rst 
-   compile.rst
 
 .. tip::
     Please help us by citing:
@@ -61,6 +61,7 @@ Installing GSAS-II: Overview
 There are several different ways to install GSAS-II, as are outlined below. Most people will use the GSAS2FULL installer
 
 .. toctree::
+   :maxdepth: 3
    :caption: Installation information:
 
    install.rst
@@ -132,7 +133,17 @@ projects. Some starting information is here:
 
    developers.rst 
 
-Miscellaneous GSAS-II Links
+Compiling GSAS-II
+======================================
+
+Creating the GSAS-II binaries when not using one of the standard
+installation methods.
+
+.. toctree::
+   
+   compile.rst
+   
+ Miscellaneous GSAS-II Links
 ======================================
 
 Other things related to GSAS-II can be found here.