search

sphinx-contrib / matlabdomain

A Sphinx extension for documenting Matlab code
Other
64 stars 45 forks source link

Inquiry on features and documentation: scripts, citations, comments and parsing of existing docs #218

Closed dazu89 closed 8 months ago

dazu89 commented 10 months ago

I am considering Sphinx' use for a project. After some experimentation with the test_data and reading through the docs, I could answer the following questions:

  1. How to document script variables, in similar way as function parameters?
  2. How to cite sources, i.e. make literature references, using for example BibTeX citation key?
  3. How to include list of specific comments in .m-files, e.g. questions or todos, somewhere in the index?
  4. How to render existing Matlab function documentation, such as Cobra Toolbox, e.g. this function? Which parts of Sphinx control the translation of capitalized comments and the translation of indented comments?
joeced commented 10 months ago

Hi

1) For scripts for we only take the first commented part as the docstring. You cannot extract documentation for individual variables. 2) Inside a MATLAB docstring you can use regular reStructuredText markup, so if you use something like https://pypi.org/project/sphinxcontrib-bibtex/, it would show up in the generated docs. 3) There is no function for that. You would have to extract that yourself with Python. 4) I'm not sure if they do it. They may have a program that a processes the docstring? Better ask at their https://github.com/opencobra/cobratoolbox/tree/master site.