Merge pull request #53 from SasView/29-documentation

29: Building sasdata documentation

.github/workflows/test.yml

@@ -59,6 +59,18 @@ jobs:
         python setup.py build
         python -m pip install .
 
+    ### Build documentation (if enabled)
+
+    - name: Install doc-building dependencies
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        python -m pip install sphinx
+
+    - name: Build sasdata docs (Ubuntu only)
+      if: matrix.os == 'ubuntu-latest'
+      run: |
+        make -C docs html
+
     - name: Test with pytest
       run: |
         python -m pytest -v -s test

.gitignore

@@ -20,7 +20,8 @@
 *.so
 *.exe
 
-/build
+**/generated
+**/build
 /dist
 .mplconfig
 

docs/Makefile

@@ -0,0 +1,48 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# Environment variables
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SPHINXAPIDOC  ?= sphinx-apidoc
+APIOPTS       = -d 8 -H SasData
+SOURCEDIR     = source
+BUILDDIR      = build
+CD            = cd
+
+ifdef ComSpec
+    RMDIR   = rmdir /s/q
+    MKDIR   = mkdir
+    PATHSEP = $(strip \)
+else
+    RMDIR   = rm -rf
+    MKDIR   = mkdir -p
+    PATHSEP = $(strip /)
+endif
+
+LIBDIR        = $(BUILDDIR)$(PATHSEP)lib
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+clean:
+	-$(RMDIR) "$(SOURCEDIR)$(PATHSEP)dev$(PATHSEP)generated/" "$(BUILDDIR)"
+
+dir:
+	-$(MKDIR) "$(BUILDDIR)"
+	-$(MKDIR) "$(LIBDIR)"
+
+.PHONY: help Makefile
+
+# Generate the api docs
+api:
+	$(SPHINXAPIDOC) -o "$(SOURCEDIR)$(PATHSEP)dev$(PATHSEP)generated/" $(APIOPTS) "$(LIBDIR)"
+
+html: dir api
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

docs/source/conf.py

@@ -0,0 +1,34 @@
+# Configuration file for the Sphinx documentation builder.
+
+# -- Project information ----------------------------------------------------
+import datetime
+import os
+
+from sasdata import __version__ as sasdata_version
+
+if os.path.exists('rst_prolog'):
+    with open('rst_prolog') as fid:
+        rst_prolog = fid.read()
+
+# General information about the project.
+year = datetime.datetime.now().year
+
+project = 'SasData'
+copyright = f'{year}, The SasView Project'
+author = 'SasView'
+release = sasdata_version
+
+# -- General configuration ---------------------------------------------------
+
+extensions = [
+    'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
+]
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+# -- Options for HTML output -------------------------------------------------
+
+html_theme = 'default'
+html_static_path = ['_static']

docs/source/dev/dev.rst

@@ -0,0 +1,11 @@
+.. dev.rst
+
+.. _dev:
+
+Developer Documentation
+=======================
+
+.. toctree::
+    :maxdepth: 1
+
+    SasData <generated/modules>

docs/source/index.rst

@@ -0,0 +1,27 @@
+.. sasdata documentation master file, created by
+   sphinx-quickstart on Wed Sep 27 16:53:29 2023.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+SasData Documentation
+=====================
+
+Contents
+--------
+
+**SasData** is a Python library for importing and exporting reduced small-angle scattering data.
+
+.. toctree::
+   :maxdepth: 1
+
+   User Documentation <user/user>
+
+   Developer Documentation <dev/dev>
+
+   Release Note <user/RELEASE>
+
+Indices and Search
+------------------
+
+* :ref:`genindex`
+* :ref:`search`

docs/source/rst_prolog

@@ -0,0 +1,4 @@
+.. Set up some substitutions to make life easier...
+
+.. |Ang| unicode:: U+212B
+.. |Ang^-1| replace:: |Ang|\ :sup:`-1`

docs/source/user/RELEASE.rst

@@ -0,0 +1,30 @@
+.. RELEASE.rst
+
+.. _Release_Notes:
+
+Release Notes
+=============
+
+.. note:: In Windows use [Alt]-[Cursor left] to return to the previous page
+
+.. toctree::
+   :maxdepth: 1
+
+Features
+========
+Wheel, egg, and tar.gz files are available on `pypi <https://pypi.org/project/sasdata/>`_.
+
+New in Version 0.8.1
+--------------------
+This is a point release to fix a build issue. The `sasdata.data_utils` package was omitted from setup.py causing an
+import issue in a separate repository.
+
+New in Version 0.8
+------------------
+This release brings sasdata into parity with the matching `SasView <https://github.com/SasView/sasview/>`_ data
+elements. With this release, the master branch will be locked and all changes will need to be made using pull requests.
+
+New in Version 0.7
+------------------
+This is the first official release of the sasdata package. This is a stand-alone package with the data
+import/export/manipulation available through the `SasView <https://github.com/SasView/sasview/>`_ application.

docs/source/user/data/data_export_help.rst

@@ -0,0 +1,61 @@
+.. data_export_help.rst
+
+.. _Exporting_data:
+
+Exporting data
+==============
+
+The `Loader().save()` method accepts 3 arguments; `path`, which is the file path to save the file into, `data`, which is the
+`Data1D` or `Data2D` object, and, optionally, `ext`, a file extension. If an extension is passed to `save`, any file extension
+in the file path will be superseded. If no file extension is given in the filename or format, a ValueError will be thrown.
+
+Save `format` options are limited to:
+  * `.xml`: for the canSAS XML format
+  * `.h5`: for the NXcanSAS format
+  * `.txt`: for the multi-column ascii format
+  * `.csv`: for a comma delimited text format
+
+.. list-table:: Save argument examples and associated data output
+   :header-rows: 1
+
+   * - filename
+     - format
+     - saved file name
+     - saved file format
+   * - 'mydata'
+     - '.csv'
+     - mydata.csv
+     - CSV format
+   * - 'mydata.xml'
+     - None
+     - mydata.xml
+     - canSAS XML format
+   * - 'mydata.xml'
+     - '.csv'
+     - mydata.xml.csv
+     - CSV format
+   * - 'mydata'
+     - None
+     - N/A
+     - raises `ValueError`
+
+To export data using the scripting interface, ensure the python environment is correctly set up and activated.
+
+.. code-block:: RST
+
+    (sasdata) $ python
+    >>> from sasdata.dataloader.loader import Loader
+    >>> loader_module = Loader()
+    >>> loaded_data_sets = loader_module.load(path="/path/to/imported/file.ext")
+    >>> loaded_data_set = loaded_data_sets[0]
+    >>> loader_module.save(path='/path/to/file/exported/filename.ext', data=loaded_data_set)
+
+Please read more on the supported :ref:`formats`.
+
+For more information on the native data structure, please see the documentation for
+`Data1D <../../dev/generated/sasdata.dataloader.html#sasdata.dataloader.data_info.Data1D>`_ for 1-dimensional data and
+`Data2D <../../dev/generated/sasdata.dataloader.html#sasdata.dataloader.data_info.Data2D>`_ for 2-dimensional data.
+
+.. ZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZZ
+
+.. note::  This help document was last modified by Jeff Krzywon, 29Sep2023