DOC: add pdfgetx v2.1.0 user manual to source

Author: chiahaoliu

products/pdfgetx.rst

@@ -70,11 +70,11 @@ Documentation
 Version 2.1.0 - latest
 ----------------------
 
-* `installation instructions <../doc/pdfgetx/2.0.0/install.html>`__
-* `user manual <../doc/pdfgetx/2.0.0/index.html>`__,
-  `printable manual <../doc/pdfgetx/2.0.0/PDFgetXN3_manual.pdf>`__
-* `tutorial files <../doc/pdfgetx/2.0.0/pdfgetxn3-examples.zip>`__
-* `release notes <../doc/pdfgetx/2.0.0/release.html>`__
+* `installation instructions <../doc/pdfgetx/2.1.0/install.html>`__
+* `user manual <../doc/pdfgetx/2.1.0/index.html>`__,
+  `printable manual <../doc/pdfgetx/2.1.0/PDFgetXNS3_manual.pdf>`__
+* `tutorial files <../doc/pdfgetx/2.1.0/pdfgetxn3-examples.zip>`__
+* `release notes <../doc/pdfgetx/2.1.0/release.html>`__
 
 Version 2.0.0
 -------------

static_root/doc/pdfgetx/2.1.0/PDFgetXNS3_manual.pdf

@@ -0,0 +1,102 @@
+Files used in PDF extraction
+========================================================================
+
+.. include:: abbreviations.txt
+.. _my-configfile:
+.. program:: pdfgetx3
+
+Configuration file
+------------------------------------------------------------------------
+
+Configuration files may define the PDF processing parameters.
+By default, the :program:`pdfgetx3` program attempts to read
+:file:`.pdfgetx3.cfg` file from the user HOME directory,
+then :file:`.pdfgetx3.cfg` and :file:`pdfgetx3.cfg` files
+from the current working directory.
+If configuration file has a different name, it needs to be specified
+with the :option:`-c, --config <-c>` option.
+The :program:`pdfgetn3` program works in the same way,
+except it checks for configuration files
+:file:`~/.pdfgetn3.cfg`, :file:`.pdfgetn3.cfg` and :file:`pdfgetn3.cfg`.
+
+The easiest way of creating a configuration file is to generate
+a template content using the :option:`--createconfig` option as ::
+
+   pdfgetx3 --createconfig=test.cfg
+
+and then change the generated test.cfg file in your favorite text
+editor.  The configuration file follows a simple "varname=value" syntax,
+any lines starting with "#" are ignored as comments.
+
+The configuration file has several sections marked as ``[SECTIONNAME]``.
+The ``[DEFAULT]`` section is mandatory and it contains the default
+global settings.  Any other sections are optional and they are applied
+only when selected with the :option:`-s, --section <-s>` option on the
+command line.  Thus ::
+
+   pdfgetx3 --config=test.cfg --section=nacl
+
+would read the parameters from the ``[nacl]`` section after reading the
+defaults.  Having several sections in the configuration
+file is useful when there are multiple measurements that share most of
+the parameters, but differ in a few of them, for example in chemical
+composition.  The configuration file can then contain sections per each
+sample that define only the composition, while all other parameters are
+specified just once in the global DEFAULT section.
+
+
+Input files
+------------------------------------------------------------------------
+
+PDFgetX3 and PDFgetN3 accept input powder diffraction data
+in the form of two-column text file,
+where the first column x is either the scattering angle
+|twotheta| in degrees, momentum transfer *Q* in inverse nanometers or *Q*
+in inverse ångströms.  The second column y contains the corresponding
+scattered intensities normalized per unit solid angle.  The actual type
+of the x-values is identified by the :confval:`dataformat` parameter.
+The input files may contain header with comments or metadata, and the
+actual data are read from the first long section of numerical values.
+
+The input files are usually passed as command-line arguments to
+:program:`pdfgetx3` or :program:`pdfgetn3` programs and must be paths
+accessible from the current working directory.
+
+Input files can be also defined by setting the :confval:`inputfile`
+value in the configuration file.  The :option:`-d, --datapath <-d>`
+option can be then used to provide additional data directories to
+search for these inputs and for the :confval:`backgroundfile`.
+This is to support configuration files located in a different
+directory than the data.
+
+When the :option:`--find <-f>` option is active, the pdfgetx3 arguments
+are understood as filename patterns and the input files are found
+in the current or specified directory.
+
+
+Output files
+------------------------------------------------------------------------
+
+PDFgetX3 and PDFgetN3 can produce up to four different output data files:
+
+* .iq -- |IQ|, the background-corrected
+  intensities sampled on a regular *Q*-space grid in inverse ångströms,
+
+* .sq -- |SQ|, the total scattering structure function,
+  with intensities normalized by average scattering factors and
+  corrected by a polynomial fit,
+
+* .fq -- |FQ|, the reduced structure function equal to *Q*\ (|SQ| - 1),
+
+* .gr -- |Gr|, the resultant PDF, where the first column is the
+  separation *r* in ångströms and the second is the function *G* in
+  Å\ :sup:`-2`.
+
+You can specify what output files should be produced by setting the
+:confval:`outputtypes` parameter in the configuration file or by
+passing the :option:`-t, --outputtypes <-t>` on the command line.
+
+The header of all output files contains the parameter values that were
+used in the calculation and thus it is by itself a valid configuration
+file.  When passed as an argument to the :option:`--config <-c>` option,
+the PDFgetX3 will reproduce the previous calculation.

static_root/doc/pdfgetx/2.1.0/_images/nickelfqgr.png

@@ -0,0 +1,38 @@
+.. PDFgetX3 documentation master file, created by
+   sphinx-quickstart on Tue Sep 21 18:35:11 2010.
+   You can adapt this file completely to your liking,
+   but it should at least contain the root `toctree` directive.
+
+########################################################################
+diffpy.pdfgetx
+########################################################################
+
+User manual for PDFgetX3, PDFgetN3, PDFgetS3 and Python package diffpy.pdfgetx.
+
+| Release |release|
+| |today|
+
+========================================================================
+Table of contents
+========================================================================
+
+
+.. toctree::
+   :maxdepth: 2
+
+   intro
+   install
+   quick-start
+   tutorial
+   files
+   interact
+   options
+   plotdata
+   release
+
+========================================================================
+Indices
+========================================================================
+
+* :ref:`genindex`
+* :ref:`search`

static_root/doc/pdfgetx/2.1.0/_images/nickelfqgrnoisy.png

@@ -0,0 +1,135 @@
+Installation
+========================================================================
+
+.. include:: abbreviations.txt
+
+Software requirements
+------------------------------------------------------------------------
+
+This software is written in Python programming language, therefore
+you must have Python 3.7, 3.6, 3.5, 3.4 or 2.7 installed.  In addition,
+the following third-party Python libraries are also required:
+
+* pip - Python package installer
+* setuptools - tools for installing Python packages
+* six - Python 2 and 3 compatibility library
+* NumPy - library for scientific computing with Python
+* matplotlib - Python plotting library
+* IPython - enhanced interactive Python shell
+
+Standard Python releases can be obtained from
+https://www.python.org/downloads.
+The third-party libraries can be found at the
+`Python Package Index <https://pypi.org>`__
+or using any Internet search engine.
+
+Another more convenient option is to obtain one of the science-oriented
+Python distributions such as
+`Anaconda Python`_,
+`Enthought Canopy <https://www.enthought.com/>`_ or
+`PythonXY <https://python-xy.github.io/>`_,
+These distributions already include all the necessary libraries, so the
+required Python software can be all installed in one step.
+
+On Linux operating systems the third-party libraries are usually
+included in a system software repository.  For example on an
+Ubuntu Linux computer the software dependencies can be all installed
+with a single shell command ::
+
+  sudo apt-get install \
+    python3-pip python3-setuptools python3-six \
+    python3-numpy python3-matplotlib ipython3
+
+This may be, of course, as well accomplished using the GUI
+driven Synaptic package manager.  Other Linux
+distributions may use different software management tools,
+but the names of the necessary packages should be very similar
+to those above.
+
+On Windows operating system, it may be necessary to add the
+``C:\Python37`` directory and the scripts directory
+``C:\Python37\Scripts`` to the system :envvar:`!PATH`. Some Python
+distributions already do so as a part of their installation process. The
+easiest way to check is to start the :program:`Command Prompt`, type
+there ``python`` and see if this starts the Python interpreter.
+
+
+Installation
+------------------------------------------------------------------------
+
+The diffpy.pdfgetx software is distributed as a Python wheel file,
+which can be obtained from the
+`Columbia Technology Ventures
+<http://innovation.columbia.edu/technologies/m11-120>`__.
+Once all the required software is in
+place, start the command prompt on Windows or a Unix terminal on Linux
+or Mac, navigate to the directory that contains the wheel file and
+execute the following command::
+
+  pip install ./diffpy.pdfgetx-VERSION.whl
+
+Here VERSION needs to be replaced to match the actual filename. It is
+critical that pip installer is from a supported Python version otherwise
+the program would not work. On Linux and Mac operating systems the installation may need to run with root user privileges, for example, by prepending ``sudo`` to the command line above. If root access is not available, use the ``pip install`` options :option:`!--user` or :option:`!--prefix` to install the software to a user-writable directory.
+
+The package provides three programs for PDF conversion, :program:`pdfgetx3`, :program:`pdfgetn3` and :program:`pdfgets3`. To check if they are correctly installed run ::
+
+  pdfgetx3 --version
+  pdfgetn3 --version
+  pdfgets3 --version
+
+This should display the software version, which should agree
+with the VERSION string in the wheel package name.
+The installation also includes a :program:`plotdata`
+command for an easy plotting of text data files.  To verify
+if plotdata works, run the ``plotdata --version`` command.
+Finally, a comprehensive test of the installed software can
+be executed using ::
+
+  python -m diffpy.pdfgetx.tests.run
+
+.. note::
+
+   Older versions of diffpy.pdfgetx use Python egg format
+   instead of Python wheel.
+   To install these use the easy_install command as follows::
+
+      python -m easy_install ./diffpy.pdfgetx-VERSION.egg
+
+.. index:: %pdfgetx3 IPython magic
+.. index:: %pdfgetn3 IPython magic
+.. index:: %pdfgets3 IPython magic
+
+IPython magic command
+------------------------------------------------------------------------
+
+These instructions are intended for `IPython`_ users who would like to
+integrate PDFgetX3, PDFgetN3 and PDFgetS3 into their IPython environment.  If
+you don't plan to customize IPython in such way you can safely skip
+this paragraph.
+
+When pdfgetx3 or pdfgetn3 or pdfgets3 is run in interactive mode, it start
+IPython interactive shell and define an extra ``%pdfgetx3``, ``%pdfgetn3`` and ``%pdfgets3`` magic commands within the IPython session.  The IPython
+magic commands are not valid Python code, but work in a similar
+fashion as standard shell commands.  The ``%pdfgetx3``, ``%pdfgetn3`` and ``%pdfgets3`` magics can be thus used with the same options and arguments as if run from the shell.  This is useful for processing more files, while
+preserving all plots or variables that were already created
+in an IPython session.
+
+The ``%pdfgetx3``, ``%pdfgetn3`` and ``%pdfgets3`` magic commands can be defined
+permanently so they are available in all IPython sessions.  To set
+this up
+
+#.  find the ``profile_default/ipython_config.py`` file and open it
+    in a text editor.  If that file does not exists,
+    create it first by executing ::
+
+      ipython profile create
+
+#.  navigate to the paragraph that contains the
+    :py:data:`!c.InteractiveShellApp.extensions` and add there
+    the following line ::
+
+      c.InteractiveShellApp.extensions = ['diffpy.pdfgetx.ipy_magics']
+
+    There must be no leading indent, i.e., the text must start at the
+    very first column.