Feature request: Online version of the documentation

[hurak]

The documentation for the toolbox contains much more than just a set of docstrings. It is so nicely developed that it can be used even as a standalone learning resource. Currently it is not possible to read the documentation without launching Matlab first, is it? It would be great if a PDF version of the documentation could be generated so that it can be read on a tablet or smartphone.

[pwintz]

You can read the documentation on the FIle Exchange project page in the Examples tab, but it's pretty cumbersome to navigate because none of the internal links will work. You might also try installing the toolbox in MATLAB Online and reading the documentation there.

We used to have a PDF file containing all of the documentation, but I think we'll stay away from that for now. Instead, I'll look into how we can host the HTML documentation on GitHub in a way that is easily navigated. I won't have time to do that soon, though, so for now, your best bet is just to use the documents in MATLAB, MATLAB Online, or on the File Exchange.

[pwintz]

I'm going to leave this open to remind myself to create online documentation.

[pwintz]

I've made an initial proof of concept on pwintz/HyEQ_Toolbox. It's mostly working, but there are the following issues to iron out:

• [x] Some links are broken. In particular, when the documentation is accessed in MATLAB Help, we do some redirects from old file names to new ones via the function hybrid.internal.openHelp.
• [x] The titles of all the help pages are the file names, which does not look very nice. We should maybe rename all of the .m files so that we get pleasant and informative page titles.
• [x] In MATLAB code blocks, there are some <span> tags injected for changing the styling of comments and keywords, but GitHub is displaying them so we should take them out.

<span class="comment">% Define properties of the system that can be modified.</span>
<span class="keyword">properties</span>
    gamma = -9.8; <span class="comment">% Acceleration due to gravity.</span>
    lambda = 0.9; <span class="comment">% Coefficient of bounce restitution.</span>
<span class="keyword">end</span>

• [x] Some symbols are incorrectly displayed as HTML entities instead (that is, '\<' instead of '<'). See, esp., Help_behavior_in_C_intersection_D
• [x] We use a tabular environment in the Network Example. This is not recognized by MathJax, apparently.

[pwintz]

I added a sidebar that shows the table of contents, but I created it manually, so I want to write a script to automatically generate it. It also looks like the link text for Help_behavior_in_C_intersection_D was lost, possible because the link text includes <tt>C</tt>

[pwintz]

Here's a new version of the website: hyeq.github.io. It's still a work in progress, so expect changes. In particular, URLs will likely change, so if you share a link to a particular page, it might break in the future.

[pwintz]

The website at hyeq.github.io is now finished. The links should be static from here on out.