easyspindoc: access local documentation directly from within MATLAB

StollLab · Aug 30, 2022 · 30ab92b · 30ab92b
1 parent 1f4cb66
commit 30ab92b
Show file tree

Hide file tree

Showing 15 changed files with 250 additions and 18 deletions.
diff --git a/docsrc/easyspin.html b/docsrc/easyspin.html
@@ -0,0 +1,84 @@
+<!DOCTYPE html>
+<html>
+<head>
+   <meta charset="utf-8">
+   <link rel="icon" href="img/eslogo196.png">
+   <link rel="stylesheet" type="text/css" href="style.css">
+   <link rel="stylesheet" href="highlight/matlab.css">
+   <script src="highlight/highlight.pack.js"></script>
+   <script>hljs.initHighlightingOnLoad();</script>
+   <title>easyspincompile</title>
+</head>
+
+<body>
+
+<header>
+<ul>
+<li><img src="img/eslogo42.png">
+<li class="header-title">EasySpin
+<li><a href="index.html">Documentation</a>
+<li><a href="references.html">Publications</a>
+<li><a href="http://easyspin.org" target="_blank">Website</a>
+<li><a href="http://easyspin.org/academy" target="_blank">Academy</a>
+<li><a href="http://easyspin.org/forum" target="_blank">Forum</a>
+</ul>
+</header>
+
+<section>
+
+<div class="functitle">easyspin</div>
+
+<p>
+Information and tasks relating to the EasySpin installation.
+</p>
+
+<!-- ============================================================= -->
+<div class="subtitle">Syntax</div>
+
+<pre class="matlab">
+easyspin info
+easyspin doc
+easyspin compile
+easyspin ?
+easyspin
+</pre>
+
+<!-- ============================================================= -->
+<div class="subtitle">Description</div>
+
+<p>
+<code>easyspin info</code>> displays information about your current EasySpin installation. See <a class="esf" href="easyspininfo.html">easyspininfo</a>.
+</p>
+
+<p>
+<code>easyspin doc</code>> opens the documentation of your current EasySpin installation. See <a class="esf" href="easyspindoc.html">easyspininfo</a>.
+</p>
+
+<p>
+<code>easyspin compile</code>> compiles the C files of your current EasySpin installation using <code>mex</code>.  See <a class="esf" href="easyspincompile.html">easyspincompile</a>.
+</p>
+
+<p>
+<code>easyspin ?</code>> displays al possible options for <code>easyspin</code>.
+</p>
+
+<p>
+<code>easyspin</code>> is equivalent to <code>easyspin info</code>.
+</p>
+
+<!-- ====================================================== -->
+<div class="subtitle">See also</div>
+
+<p>
+<a class="esf" href="easyspincompile.html">easyspincompile</a>,
+<a class="esf" href="easyspindoc.html">easyspindoc</a>,
+<a class="esf" href="easyspininfo.html">easyspininfo</a>
+</p>
+
+<hr>
+</section>
+
+<footer></footer>
+
+</body>
+</html>
diff --git a/docsrc/easyspincompile.html b/docsrc/easyspincompile.html
@@ -53,6 +53,16 @@
 be set up first with <code>mex -setup</code>.
 </p>
 
+<!-- ====================================================== -->
+<div class="subtitle">See also</div>
+
+<p>
+<a class="esf" href="easyspin.html">easyspin</a>,
+<a class="esf" href="easyspindoc.html">easyspindoc</a>,
+<a class="esf" href="easyspininfo.html">easyspininfo</a>
+</p>
+
+
 <hr>
 </section>
 

diff --git a/docsrc/easyspindoc.html b/docsrc/easyspindoc.html
@@ -0,0 +1,64 @@
+<!DOCTYPE html>
+<html>
+<head>
+   <meta charset="utf-8">
+   <link rel="icon" href="img/eslogo196.png">
+   <link rel="stylesheet" type="text/css" href="style.css">
+   <link rel="stylesheet" href="highlight/matlab.css">
+   <script src="highlight/highlight.pack.js"></script>
+   <script>hljs.initHighlightingOnLoad();</script>
+   <title>easyspininfo</title>
+</head>
+
+<body>
+
+<header>
+<ul>
+<li><img src="img/eslogo42.png">
+<li class="header-title">EasySpin
+<li><a href="index.html">Documentation</a>
+<li><a href="references.html">Publications</a>
+<li><a href="http://easyspin.org" target="_blank">Website</a>
+<li><a href="http://easyspin.org/academy" target="_blank">Academy</a>
+<li><a href="http://easyspin.org/forum" target="_blank">Forum</a>
+</ul>
+</header>
+
+<section>
+
+<div class="functitle">easyspindoc</div>
+
+<p>
+Access the documentation of EasySpin.
+</p>
+
+<!-- ============================================================= -->
+<div class="subtitle">Syntax</div>
+
+<pre class="matlab">
+easyspindoc
+</pre>
+
+<!-- ============================================================= -->
+<div class="subtitle">Description</div>
+
+<p>
+<code>easyspindoc</code>> opens the EasySpin documentation in the MATLAB browser. It opens <code>documentation/index.html</code> in your local EasySpin installation.
+</p>
+
+<!-- ====================================================== -->
+<div class="subtitle">See also</div>
+
+<p>
+<a class="esf" href="easyspin.html">easyspin</a>,
+<a class="esf" href="easyspincompile.html">easyspincompile</a>,
+<a class="esf" href="easyspininfo.html">easyspininfo</a>
+</p>
+
+<hr>
+</section>
+
+<footer></footer>
+
+</body>
+</html>
diff --git a/docsrc/easyspininfo.html b/docsrc/easyspininfo.html
@@ -53,6 +53,15 @@
 EasySpin functions and other functions on the MATLAB path.
 </p>
 
+<!-- ====================================================== -->
+<div class="subtitle">See also</div>
+
+<p>
+<a class="esf" href="easyspin.html">easyspin</a>,
+<a class="esf" href="easyspincompile.html">easyspincompile</a>,
+<a class="esf" href="easyspindoc.html">easyspindoc</a>
+</p>
+
 <hr>
 </section>
 

diff --git a/docsrc/funcsalphabet.html b/docsrc/funcsalphabet.html
@@ -58,6 +58,7 @@
 <tr><td><a href="dipkernel.html">dipkernel</a></td><td>Dipolar EPR signal (DEER)</td></tr>
 <tr><td><a href="diptensor.html">diptensor</a></td><td>Dipolar tensors</td></tr>
 <tr><td><a href="easyspincompile.html">easyspincompile</a></td><td>Compile EasySpin</td></tr>
+<tr><td><a href="easyspindoc.html">easyspindoc</a></td><td>Access EasySpin documentation</td></tr>
 <tr><td><a href="easyspininfo.html">easyspininfo</a></td><td>Information about EasySpin installation</td></tr>
 <tr><td><a href="echarge.html">echarge</a></td><td>Elementary electric charge</td></tr>
 <tr><td><a href="eeint.html">eeint</a></td><td>Electron-electron interaction Hamiltonian</td></tr>

diff --git a/docsrc/funcscategory.html b/docsrc/funcscategory.html
@@ -31,7 +31,9 @@
 <table>
 <tr><td colspan="2" class="grouptitle">General</td></tr>
 
-<tr><td width="100"><a href="easyspininfo.html">easyspininfo</a></td><td>Information about EasySpin installation</td></tr>
+<tr><td><a href="easyspin.html">easyspin</a></td><td>Information and tasks relating to the EasySpin installation</td></tr>
+<tr><td><a href="easyspindoc.html">easyspindoc</a></td><td>Access EasySpin documentation</td></tr>
+<tr><td><a href="easyspininfo.html">easyspininfo</a></td><td>Information about EasySpin installation</td></tr>
 <tr><td><a href="easyspincompile.html">easyspincompile</a></td><td>Compile EasySpin</td></tr>
 
 <tr><td>&nbsp;</td></tr>

diff --git a/docsrc/installation.html b/docsrc/installation.html
@@ -61,7 +61,7 @@
 In MATLAB, type <code>easyspin</code> at the command prompt. This will display information about the installed version of EasySpin. Also, it might try to compile a few files from the <code>easyspin/private</code> folder. Possibly you are asked to select or install a C compiler. See below for information on how to proceed in that case.
 
 <li><b>Documentation</b><br>
-Set up bookmarks for the EasySpin documentation. Online, you can go to <a href="easyspin.org">easyspin.org</a> to view the online documentation. To view the offline documentation, point your web browser to <code>documentation/index.html</code> in your <i>EasySpin</i> installation directory and bookmark that page.
+There are several ways to access the documentation. To view the documentation of your local EasySpin installation, type <code>easyspindoc</code> or <code>easyspin doc</code> in the command window, or point your web browser to <code>documentation/index.html</code> in your <i>EasySpin</i> folder and bookmark that page. Alternatively, you can go to <a href="easyspin.org">easyspin.org</a> to view the online documentation of the most recent version of EasySpin (which might be different from the one you installed locally).
 </ol>
 
 <div class="subtitle">Compiling mex files</div>

diff --git a/docsrc/releases.html b/docsrc/releases.html
@@ -55,6 +55,7 @@ <h1>Changes from release to release</h1>
 <li>Photoselection is now supported when simulating EPR spectra of photo-generated species. See function <a class="esf" href="photoselect.html">photoselect</a>.</li>
 <li>Significantly extended support for spin-polarized systems (triplets, radical pairs, etc.) in <a class="esf" href="pepper.html">pepper</a> with the new fields <a class="matlab">Sys.initState</a>.</li>
 <li><a class="esf" href="cgmatrix.html">cgmatrix</a> has additional input and output options.</li>
+<li>Access the EasySpin documentation directly with <a class="esf" href="easyspindoc.html">easyspindoc</a> and <a class="esf" href="easyspin.html">easyspin doc</a>.</li>
 </ul>
 
 <p>Major bug fixes</p>

diff --git a/easyspin/easyspin.m b/easyspin/easyspin.m
@@ -1,11 +1,38 @@
 % easyspin   Toolbox for Electron Paramagnetic Resonance (EPR)
 %
-%   'easyspin' tests the EasySpin installation and prints release details.
+%  easyspin
+%  easyspin ?
+%  easyspin doc
+%  easyspin info
+%  easyspin compile
+%
+%   If a parameter is given, various tasks are performed:
+%     ?        show options
+%     doc      display EasySpin documentation
+%     info     display information about current EasySpin installation
+%     compile  compile MEX files for EasySpin
+%
+%  If no parameter is given, 'info' is used by default.
 
-function easyspin
+function easyspin(str)
 
-warning('off','MATLAB:oldPfileVersion');
+if nargin==0
+  str = 'info';
+end
 
-easyspininfo
+switch str
+  case '?'
+    dips(' easyspin info       Display information about EasySpin');
+    disp(' easyspin doc        Display EasySpin documentation');
+    disp(' easyspin compile    Compile MEX files for EasySpin');
+  case 'info'
+    easyspininfo;
+  case 'doc'
+    easyspindoc;
+  case 'compile'
+    easyspincompile;
+  otherwise
+    error('Unknown option ''%s''.',str);
+end
 
 end
diff --git a/easyspin/easyspincompile.m b/easyspin/easyspincompile.m
@@ -1,7 +1,5 @@
 function easyspincompile
 
-warning('off','MATLAB:oldPfileVersion');
-
 disp('EasySpin compilation');
 
 % Determine directory containing mex source files

diff --git a/easyspin/easyspindoc.m b/easyspin/easyspindoc.m
@@ -0,0 +1,21 @@
+% easyspindoc  Provide access to the EasySpin documentation
+
+function varargout = easyspindoc()
+
+% Determine entry point for documentation
+esPath = fileparts(which(mfilename));
+esRoot = esPath(1:end-length('\easyspin'));
+docEntry = [esRoot filesep 'documentation' filesep 'index.html'];
+if ~exist(docEntry,'file')
+  docEntry = [esRoot filesep 'docsrc' filesep 'index.html'];
+end
+
+if nargout==0
+  fprintf('<a href="%s">EasySpin documentation</a>\n',docEntry);
+  web(docEntry,'-new');
+  varargout = {};
+else
+  varargout = {docEntry};
+end
+
+end
diff --git a/easyspin/easyspininfo.m b/easyspin/easyspininfo.m
@@ -12,7 +12,7 @@
 % Determine EasySpin path.
 %-------------------------------------------------------------------------------
 esPath = fileparts(which(mfilename));
-AllFiles = what(esPath);
+allFiles = what(esPath);
 
 % Get release information.
 %-------------------------------------------------------------------------------
@@ -43,7 +43,7 @@
 % Check if mex files are available, compile if necessary
 %-------------------------------------------------------------------------------
 % Get list of mex files from C source files in private subfolder
-SrcFiles = dir([esPath '/private/*.c']);
+SrcFiles = dir([esPath filesep 'private' filesep '*.c']);
 nSrcFiles = numel(SrcFiles);
 for k = 1:nSrcFiles
   MexFiles{k} = SrcFiles(k).name(1:end-2);
@@ -72,14 +72,15 @@
 % Display information
 %-------------------------------------------------------------------------------
 if Display
+  fprintf('==================================================================\n');
+  fprintf('Information about the installed EasySpin version\n');
   fprintf('==================================================================\n');
   fprintf('  Release:          %s (%s)\n',esVersion,esDate);
 end
 
-Diagnostics = true;
-if Diagnostics && Display
+if Display
   fprintf('  Expiry date:      %s\n',esExpiryDate);
-  fprintf('  Folder:           %s\n',esPath);
+  fprintf('  Root folder:      %s\n',esPath(1:end-length('\easyspin')));
   fprintf('  MATLAB version:   %s\n',builtin('version'));
   fprintf('  Platform:         %s\n',platform);
   MexFiles = dir([esPath filesep 'private' filesep '*.c']);
@@ -95,6 +96,15 @@
   fprintf('\n');
   fprintf('  System date:      %s\n',datestr(now));
   fprintf('  Temp dir:         %s\n',tempdir);
+  fprintf('------------------------------------------------------------------\n');
+
+  % Display information about how to access the documentation
+  docEntry = easyspindoc;
+  fprintf('  To access the documentation:\n');
+  fprintf('  - Click <a href="%s">here</a>\n',docEntry);
+  fprintf('  - In the command window, type easyspin doc\n')
+  fprintf('  - In the command window, type easyspindoc\n')
+  fprintf('  - Point your browser to <a href="%s">%s</a>\n',docEntry,docEntry);
   fprintf('==================================================================\n');
 
   % Check online for update
@@ -127,9 +137,9 @@
 end
 Shadowing = {};
 Shadowed = {};
-for iFunction = 1:length(AllFiles.m)
-  if ~isempty(strfind(AllFiles.m{iFunction},'Contents')); continue; end
-  Instances = which(AllFiles.m{iFunction},'-all');
+for iFunction = 1:length(allFiles.m)
+  if ~isempty(strfind(allFiles.m{iFunction},'Contents')); continue; end
+  Instances = which(allFiles.m{iFunction},'-all');
 
   % Remove MATLAB class methods.
   % Class methods are only called for objects of their class.

diff --git a/easyspin/easyspinupdate.m b/easyspin/easyspinupdate.m
@@ -44,7 +44,7 @@ function easyspinupdate(OnlineVersion)
 end
 
 if isOffline
-  msg = 'You have to be connect to the internet to update EasySpin.';
+  msg = 'Could not reach EasySpin server. You have to be connect to the internet to update EasySpin.';
   disp(msg)
   return
 end

diff --git a/easyspin/easyspinversioncheck.m b/easyspin/easyspinversioncheck.m
@@ -73,7 +73,7 @@
 
 
   if isOffline
-    msg = 'You need to be connect to the internet to check for a new EasySpin version or to update.';
+    msg = 'Could not reach EasySpin server. You need to be connect to the internet to check for a new EasySpin version or to update.';
     if messages; disp(msg); end
     varargout = {0 []};
     return

diff --git a/tests/easyspindoc_syntax.m b/tests/easyspindoc_syntax.m
@@ -0,0 +1,5 @@
+function ok = test()
+
+docEntry = easyspindoc;
+ref = "index.html";
+ok = docEntry(end-strlength(ref)+1:end)==ref;