Hi all, Sorry, things have been so quiet here on the developers list. I know I’m not nearly as good at communicating with all of you as I should be.
I’ve been hard at work on MP-Element<https://github.com/MATPOWER/mp-element/>, which is turning out to be essentially a complete rewrite of MATPOWER to make it many times more flexible and powerful. More on that to come. However, the reason for this e-mail is to get suggestions and comments (and hopefully some help) regarding documentation infrastructure for upcoming versions of MATPOWER. I have a lot of new code that needs to be properly documented before it can be released. Many languages make it easy to pull documentation text directly from the code files to generate reference documentation. And there are tools that allow multiple formats (especially HTML and PDF) to be generated from a single set of source documents. In particular, Python’s documentation<https://docs.python.org> is based on Sphinx<https://www.sphinx-doc.org>, as are the many projects hosted by Read the Docs<https://readthedocs.org>, and it turns out that Sphinx supports a contributed “domain” for handling Matlab documentation as well. The following are some of my goals for MATPOWER documentation going forward: * Keep all help text in the code compatible with MATLAB’s help and doc commands, and as close as possible to MathWorks conventions. * Use Sphinx to automatically generate reference documentation directly from the code and embedded help text. * Write all of the documentation in reStructuredText (reST) format, so Sphinx can be used to generate HTML and PDF versions of everything. The big questions are, does anyone here have … … experience with Sphinx (with Matlab code or otherwise)? … suggestions for an alternative? You feedback is greatly appreciated. Thanks, Ray
