Add README content to Sphinx User's Manual.

CHANGES.md

@@ -6,7 +6,7 @@ Since 8.0b1
 -----------
 
 #### 3/1/24
-  - Add Sphinx-based Reference documentation.
+  - Add Sphinx-based User and Reference documentation.
 
 
 Version 8.0b1 - *Dec 12, 2022*

README.md

@@ -2,7 +2,7 @@ MP-Test
 =======
 
 MP-Test is a set of functions for implementing unit testing in MATLAB or
-Octave. It was initially developed for [MATPOWER][1], and is used by
+GNU Octave. It was initially developed for [MATPOWER][1], and is used by
 [MATPOWER][1], [MATPOWER Interior Point Solver (MIPS)][2], [MP-Opt-Model][7]
 and [MATPOWER Optimal Scheduling Tool (MOST)][3]. It also includes a
 function `have_feature` for detecting support for optional functionality.
@@ -42,8 +42,9 @@ of MATLAB or Octave, including setting up your MATLAB/Octave path.
 Usage
 -----
 
-*   Write test functions of the following form, where `t_ok` and `t_is` are
-    used to test for specific conditions or matches, respectively.
+*   Write test functions of the following form, where `t_ok`, `t_is`,
+    `t_str_match`, and `t_file_match` are used to test for specific
+    conditions or matches.
 ```matlab
   function mptest_ex1(quiet)
   if nargin < 1

docs/sphinx/source/index.rst

@@ -2,10 +2,132 @@
 |MPTEST| User's Manual
 ######################
 
-.. note::
+..
+    .. note::
+    
+       The new web-based version of the |MPTEST| User's Manual is not yet available. Please, continue to use the |MPTESTman| on GitHub for now.
 
-   The new web-based version of the |MPTEST| User's Manual is not yet available. Please, continue to use the |MPTESTman| on GitHub for now.
+|MPTEST>| is a set of functions for implementing unit testing in |MATLAB>| or
+|Octave>|. It was initially developed for |MATPOWER>|, and is used by
+|MATPOWER>|, |MIPSname| (|MIPS>|), |MPOM>|, and |MOSTname| (|MOST>|),
+among many other packages. It also includes a function
+:func:`have_feature` for detecting support for optional functionality.
+
+Installation
+============
+
+**Note to** |*MATPOWER*| **users:** *MP-Test is included when you install*
+|/MATPOWER/|. *There is generally no need to install it separately. You
+can skip directly to step 3 to verify.*
+
+Installation and use of |MPTEST>| requires familiarity with the basic operation
+of MATLAB or Octave, including setting up your MATLAB/Octave path.
+
+1.  Clone the repository or download and extract the zip file of the |MPTEST|
+    distribution from the |MPTEST>| `project page
+    <https://github.com/MATPOWER/mptest>`_ to the location of your
+    choice. The files in the resulting ``mptest`` or ``mptestXXX`` directory,
+    where ``XXX`` depends on the version of |MPTEST|, should not need to be
+    modified, so it is recommended that they be kept separate from your
+    own code. We will use :samp:`{<MPTEST>}` to denote the path to this
+    directory.
+
+2.  Add the following directories to your MATLAB/Octave path:
+
+    - :samp:`{<MPTEST>}/lib`
+    - :samp:`{<MPTEST>}/lib/t`
+
+3.  At the |MATLAB|/Octave prompt, type ``test_mptest`` to run the test suite
+    and verify that |MPTEST| is properly installed and functioning. The result
+    should resemble the following::
+
+        >> test_mptest
+        t_test_fcns.......ok
+        t_have_feature....ok
+        All tests successful (29 of 29)
+        Elapsed time 0.18 seconds.
+
+
+Usage
+=====
+
+Write test functions of the following form, where :func:`t_ok`,
+:func:`t_is`, :func:`t_str_match`, and :func:`t_file_match` are used to
+test for specific conditions or matches.
+::
+
+    function mptest_ex1(quiet)
+    if nargin < 1
+        quiet = 0;
+    end
+    t_begin(4, quiet);
+    t_ok(pi > 3, 'size of pi');
+    if have_feature('octave')
+        t_ok(1, 'Octave-only test foo');
+        t_ok(1, 'Octave-only test bar');
+    else
+        t_skip(2, 'foo and bar tests require Octave');
+    end
+    t_is(2+2, 4, 12, '2+2 still equals 4');
+    t_end;
+
+Then run your test function:
+
+.. code-block:: text
+
+    >> mptest_ex1
+    1..4
+    ok 1 - size of pi
+    skipped 2..3 - foo and bar tests require Octave
+    ok 4 - 2+2 still equals 4
+    All tests successful (2 passed, 2 skipped of 4)
+    Elapsed time 0.00 seconds.
+
+If you have several test functions, create a function to run them all as
+follows::
+
+    function test_everything_ex1(verbose)
+    if nargin < 1
+        verbose = 0;
+    end
+    tests = {};
+    tests{end+1} = 'mptest_ex1';
+    tests{end+1} = 't_test_fcns';
+    
+    t_run_tests( tests, verbose );
+
+Run all of your tests at once. The output may look something like:
+
+.. code-block:: text
+
+    >> test_everything_ex1
+    mptest_ex1.....ok (2 of 4 skipped)
+    t_test_fcns....ok
+    All tests successful (7 passed, 2 skipped of 9)
+    Elapsed time 0.09 seconds.
+
+
+Documentation
+=============
+
+The primary sources of documentation for |MPTEST| are this User's Manual, especially the :ref:`sec_mptest_reference` section, and the built-in ``help`` command. As with the built-in functions and toolbox routines in |MATLAB>| and |Octave>|, you can type ``help`` followed by the name of a command or M-file to get help on that particular function.
 
 .. toctree::
 
    reference
+
+
+Contributing
+============
+
+Please see our `contributing guidelines <https://github.com/MATPOWER/mptest/blob/master/CONTRIBUTING.md>`_ for details on how to contribute to the project or report issues.
+
+License
+=======
+
+|MPTEST| is distributed under the `3-clause BSD license <https://github.com/MATPOWER/mptest/blob/master/LICENSE>`_.
+
+Acknowledgments
+===============
+
+This material is based upon work supported in part by the |CERTS| and the Office of Electricity Delivery and Energy Reliability, Transmission Reliability Program of the U.S. Department of Energy under the National Energy Technology Laboratory Cooperative Agreement No. DE-FC26-09NT43321 and by the National Science Foundation under Grant Nos. 0532744, 1642341 and 1931421. Any opinions, findings, and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the funding agencies.

docs/sphinx/source/reference.rst

@@ -1,9 +1,13 @@
+.. _sec_mptest_reference:
+
 Reference
 =========
 
 
-Test Functions
---------------
+Testing Functions
+-----------------
+
+Use these functions in implementing your own tests.
 
 .. toctree::
 
@@ -20,19 +24,35 @@ Test Functions
 Other Functions
 ---------------
 
+Use these functions to test for availability and version information for
+optional functionality and to check the version of the installed |MPTEST|.
+
 .. toctree::
 
    functions/have_feature
-   functions/have_feature_matlab
-   functions/have_feature_octave
    functions/mptestver
 
 
-Testing MP-Test
----------------
+Tests of MP-Test
+----------------
+
+These functions test that |MPTEST| is installed and functioning as expected.
 
 .. toctree::
 
    functions/test_mptest
    functions/t_have_feature
    functions/t_test_fcns
+
+
+Private Functions
+-----------------
+
+The following are private functions that implement detection of specific
+optional functionality. They are not intended to be called directly, but
+rather are used to extend the capabilities of :func:`have_feature` *(see above)*.
+
+.. toctree::
+
+   functions/have_feature_matlab
+   functions/have_feature_octave

lib/have_feature_matlab.m

@@ -1,8 +1,8 @@
 function [TorF, vstr, rdate] = have_feature_matlab()
 % have_feature_matlab - Detect availability/version info for MATLAB.
 %
-% Feature detection function implementing ``'matlab'`` tag for have_feature
-% to detect whether code is running under MATLAB.
+% Private feature detection function implementing ``'matlab'`` tag for
+% have_feature to detect whether code is running under MATLAB.
 %
 %   See also have_feature.
 

lib/have_feature_octave.m

@@ -1,8 +1,8 @@
 function [TorF, vstr, rdate] = have_feature_octave()
 %have_feature_octave - Detect availability/version info for GNU Octave.
 %
-% Feature detection function implementing ``'octave'`` tag for have_feature
-% to detect whether code is running under GNU Octave.
+% Private feature detection function implementing ``'octave'`` tag for
+% have_feature to detect whether code is running under GNU Octave.
 %
 % See also have_feature.