Fix wrong hyperlinks in documentation

Sphinx generates a redundant html-file 'source.html'. Each internal href,
derived from a link to a class/method/attribute, links source.html and
not the corresponding file (e.g. EV3.html when referencing EV3.connect()).
The postprocessing script now fixes these wrong links.

docs/_build/html/EV3.html

@@ -150,6 +150,16 @@
 <p>This is the 'central' class (from user's view) when working with this toolbox. It
 delivers a convenient interface for creating a connection to the brick and sending
 commands to it. An EV3-object creates 4 Motor- and 4 Sensor-objects, one for each port.</p>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference internal" href="#source.EV3.setProperties" title="source.EV3.setProperties"><code class="xref mat mat-meth docutils literal"><span class="pre">setProperties()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.beep" title="source.EV3.beep"><code class="xref mat mat-meth docutils literal"><span class="pre">beep()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.stopAllMotors" title="source.EV3.stopAllMotors"><code class="xref mat mat-meth docutils literal"><span class="pre">stopAllMotors()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.playTone" title="source.EV3.playTone"><code class="xref mat mat-meth docutils literal"><span class="pre">playTone()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.stopTone" title="source.EV3.stopTone"><code class="xref mat mat-meth docutils literal"><span class="pre">stopTone()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.tonePlayed" title="source.EV3.tonePlayed"><code class="xref mat mat-meth docutils literal"><span class="pre">tonePlayed()</span></code></a></li>
+</ul>
+</div></blockquote>
 <p class="rubric">Notes</p>
 <ul class="simple">
 <li>Creating multiple EV3 objects and connecting them to different physical bricks has not
@@ -221,13 +231,13 @@ follows: <em>brickObject.motorA.setProperties('power', 50);</em></li>
 <dl class="attribute">
 <dt id="source.EV3.batteryMode">
 <code class="descname">batteryMode</code><a class="headerlink" href="#source.EV3.batteryMode" title="Permalink to this definition">¶</a></dt>
-<dd><p><em>string in {'Percentage', 'Voltage'}</em> &#8211; Mode for reading battery charge. See also <a class="reference internal" href="source.html#source.EV3.batteryValue" title="source.EV3.batteryValue"><code class="xref mat mat-attr docutils literal"><span class="pre">batteryValue</span></code></a>. <em>[WRITABLE]</em></p>
+<dd><p><em>string in {'Percentage', 'Voltage'}</em> &#8211; Mode for reading battery charge. See also <a class="reference internal" href="#source.EV3.batteryValue" title="source.EV3.batteryValue"><code class="xref mat mat-attr docutils literal"><span class="pre">batteryValue</span></code></a>. <em>[WRITABLE]</em></p>
 </dd></dl>
 
 <dl class="attribute">
 <dt id="source.EV3.batteryValue">
 <code class="descname">batteryValue</code><a class="headerlink" href="#source.EV3.batteryValue" title="Permalink to this definition">¶</a></dt>
-<dd><p><em>numeric</em> &#8211; Current battery charge. Depending on batteryMode, the reading is either in percentage or voltage. See also <a class="reference internal" href="source.html#source.EV3.batteryMode" title="source.EV3.batteryMode"><code class="xref mat mat-attr docutils literal"><span class="pre">batteryMode</span></code></a>. <em>[READ-ONLY]</em></p>
+<dd><p><em>numeric</em> &#8211; Current battery charge. Depending on batteryMode, the reading is either in percentage or voltage. See also <a class="reference internal" href="#source.EV3.batteryMode" title="source.EV3.batteryMode"><code class="xref mat mat-attr docutils literal"><span class="pre">batteryMode</span></code></a>. <em>[READ-ONLY]</em></p>
 </dd></dl>
 
 <dl class="attribute">
@@ -287,7 +297,7 @@ b.connect('bt', 'serPort', '/dev/rfcomm0'); % <br />
 % Setup usb connection, beep when connection has been established
 b = EV3(); % <br />
 b.connect('usb', 'beep', 'on', ); % <br /></p>
-<p>See also ISCONNECTED / <a class="reference internal" href="source.html#source.EV3.isConnected" title="source.EV3.isConnected"><code class="xref mat mat-attr docutils literal"><span class="pre">isConnected</span></code></a></p>
+<p>See also ISCONNECTED / <a class="reference internal" href="#source.EV3.isConnected" title="source.EV3.isConnected"><code class="xref mat mat-attr docutils literal"><span class="pre">isConnected</span></code></a></p>
 </dd></dl>
 
 <dl class="method">
@@ -350,7 +360,7 @@ second. <br /></p>
 b.connect('bt', 'serPort', '/dev/rfcomm0'); % <br />
 b.setProperties('debug', 'on', 'batteryMode', 'Voltage'); % <br />
 % Instead of: b.debug = 'on'; b.batteryMode = 'Voltage'; % <br /></p>
-<p>See also EV3.DEBUG, EV3.BATTERYMODE / <a class="reference internal" href="source.html#source.EV3.debug" title="source.EV3.debug"><code class="xref mat mat-attr docutils literal"><span class="pre">debug</span></code></a>, <a class="reference internal" href="source.html#source.EV3.batteryMode" title="source.EV3.batteryMode"><code class="xref mat mat-attr docutils literal"><span class="pre">batteryMode</span></code></a></p>
+<p>See also EV3.DEBUG, EV3.BATTERYMODE / <a class="reference internal" href="#source.EV3.debug" title="source.EV3.debug"><code class="xref mat mat-attr docutils literal"><span class="pre">debug</span></code></a>, <a class="reference internal" href="#source.EV3.batteryMode" title="source.EV3.batteryMode"><code class="xref mat mat-attr docutils literal"><span class="pre">batteryMode</span></code></a></p>
 </dd></dl>
 
 <dl class="method">

docs/_build/html/source.html

@@ -140,6 +140,16 @@
 <p>This is the &#8216;central&#8217; class (from user&#8217;s view) when working with this toolbox. It
 delivers a convenient interface for creating a connection to the brick and sending
 commands to it. An EV3-object creates 4 Motor- and 4 Sensor-objects, one for each port.</p>
+<blockquote>
+<div><ul class="simple">
+<li><a class="reference internal" href="#source.EV3.setProperties" title="source.EV3.setProperties"><code class="xref mat mat-meth docutils literal"><span class="pre">setProperties()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.beep" title="source.EV3.beep"><code class="xref mat mat-meth docutils literal"><span class="pre">beep()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.stopAllMotors" title="source.EV3.stopAllMotors"><code class="xref mat mat-meth docutils literal"><span class="pre">stopAllMotors()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.playTone" title="source.EV3.playTone"><code class="xref mat mat-meth docutils literal"><span class="pre">playTone()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.stopTone" title="source.EV3.stopTone"><code class="xref mat mat-meth docutils literal"><span class="pre">stopTone()</span></code></a></li>
+<li><a class="reference internal" href="#source.EV3.tonePlayed" title="source.EV3.tonePlayed"><code class="xref mat mat-meth docutils literal"><span class="pre">tonePlayed()</span></code></a></li>
+</ul>
+</div></blockquote>
 <p class="rubric">Notes</p>
 <ul class="simple">
 <li>Creating multiple EV3 objects and connecting them to different physical bricks has not

docs/process.py

@@ -14,33 +14,33 @@ def preprocess():
 
     code_dir = os.path.abspath('../source')
     files = _matlab_files(os.listdir(code_dir))
-    
+
     n_files = len(files)
     for n, file_name in enumerate(files):
         # print("Preprocessing file {0} [{1}|{2}]".format(file_name, n+1, n_files))
         try:
             fh, abs_path = mkstemp()
             with open(code_dir + "/" + file_name, 'r') as f:
-                with open(abs_path, 'w') as ftemp: 
+                with open(abs_path, 'w') as ftemp:
                     content = f.readlines()
                     if content[0] == '%TEMP-FILE FOR BUILDING DOCUMENTATION\n':
                         raise RuntimeError('Found already preprocessed file: ' + file_name)
 
                     try:
-                        for i, line in enumerate(content):  # Worst runtime ever 
+                        for i, line in enumerate(content):  # Worst runtime ever
                             if _ignore_line(line) is False and 'enumeration' in line:
                                 ftemp.write('%TEMP-FILE FOR BUILDING DOCUMENTATION\n')
                                 _write_lines(content[:i], ftemp)
                                 for j, enum_line in enumerate(content[i:]):
                                    ftemp.write(" %"+enum_line)
-                                   if " end" in enum_line or "end\n" == enum_line:		
+                                   if " end" in enum_line or "end\n" == enum_line:
                                         _write_lines(content[i+1+j:], ftemp)
                                         close(fh)
                                         remove(code_dir + "/" + file_name)
                                         move(abs_path, code_dir + "/" + file_name)
                                         # At this point, entire file has been processed: continue outer loop
                                         # Hackily implemented by raising an exception
-                                        raise StopIteration  
+                                        raise StopIteration
                     except StopIteration:
                         continue
         except IOError:
@@ -49,14 +49,14 @@ def preprocess():
 def postprocess():
     code_dir = os.path.abspath('../source')
     files = _matlab_files(os.listdir(code_dir))
-    
+
     n_files = len(files)
     for n, file_name in enumerate(files):
         # print("Postprocessing file {0} [{1}|{2}]".format(file_name, n+1, n_files))
         try:
             fh, abs_path = mkstemp()
             with open(code_dir + "/" + file_name, 'r') as f:
-                with open(abs_path, 'w') as ftemp: 
+                with open(abs_path, 'w') as ftemp:
                     content = f.readlines()
                     if content[0] != '%TEMP-FILE FOR BUILDING DOCUMENTATION\n':
                         continue
@@ -73,20 +73,20 @@ def postprocess():
                                         move(abs_path, code_dir + "/" + file_name)
                                         # At this point, entire file has been processed: continue outer loop
                                         # Hackily implemented by raising an exception
-                                        raise StopIteration 
+                                        raise StopIteration
                     except StopIteration:
                         continue
         except IOError:
             pass
 
     postprocess_html_files()
-    
+
 def postprocess_html_files():
     documented_classes = ['Motor', 'Sensor', 'EV3', 'usbBrickIO', 'btBrickIO']
-        
+
     for file_name in documented_classes:
         current_file = os.path.abspath('_build/html/' + file_name + '.html')
-        try: 
+        try:
             fh, abs_path = mkstemp()
             with open(current_file, 'r') as f_old:
                 with open(abs_path, 'w') as f_new:
@@ -97,12 +97,16 @@ def postprocess_html_files():
                         # creation of the html-files, ' has been replaced by ` for some reason. :(
                         if('&#8216' in line or '&#8217' in line):
                             line = line.replace('‘', '\'').replace('’', '\'')
-                        
-                        # Delete module name from class documentation 
+
+                        # Delete module name from class documentation
                         ugly_module_string = '<code class="descclassname">source.</code>'
                         if(ugly_module_string in line):
                             line = line.replace(ugly_module_string, '')
 
+                        wrong_href = 'source.html'
+                        if(wrong_href in line):
+                            line = line.replace(wrong_href, '')
+
                         f_new.write(line)
                     close(fh)
                     remove(current_file)
@@ -110,7 +114,7 @@ def postprocess_html_files():
         except IOError:
             print('WARNING: Couldn''t postprocess html-file ' + current_file)
             continue
-      
+
 def _ignore_line(line) -> bool:
     return (line.startswith('%') or line == '\n' or line == '')
 
@@ -119,4 +123,4 @@ def _write_lines(lines, f):
         f.write(line)
 
 def _matlab_files(files) -> list:
-    return [f for f in files if (f.endswith(".m") and "_" not in f and "proto" not in f)]	
+    return [f for f in files if (f.endswith(".m") and "_" not in f and "proto" not in f)]