BICCN / cell-locator

manually align specimens to annotated 3D spaces
https://cell-locator.readthedocs.io
Other
19 stars 7 forks source link

Support generating sphinx doc #177

Closed allemangD closed 3 years ago

allemangD commented 3 years ago

Notable changes I've made since @jcfr's contributions:

One note regarding MyST - if we ever want to do reference-style documentation of the classes (see pillow's api reference, for example), we will still have to use reStructuredText. These types of docs use one or both of sphinx.ext.autodoc and sphinx python domain, neither of which is supported by MyST. I began creating such documentation to replace this code block and ran into the issue.

Docs are published at https://cell-locator.readthedocs.io/en/support-generating-sphinx-doc/

Resolves #162.

allemangD commented 3 years ago

Also worth noting there is a sphinx c++ domain for reference documentation; this also requires use of reST, and I don't think there is any autodoc available like for Python.

allemangD commented 3 years ago

There is a workaround to render reference docs and autodoc, mentioned here; enclose the problematic section in an eval-rst directive.

https://github.com/executablebooks/MyST-Parser/issues/163#issuecomment-679907892

jcfr commented 3 years ago

and I don't think there is any autodoc available like for Python

Indeed. That said, there is the possibility to integrate with doxygen using https://breathe.readthedocs.io/en/latest/

jcfr commented 3 years ago

I updated the readthedocs settings and the currently active version is now "latest" see https://cell-locator.readthedocs.io/en/latest/ and https://cell-locator.readthedocs.io