search

cpitclaudel / alectryon

A collection of tools for writing technical documents that mix Coq code and prose.
MIT License
228 stars 36 forks source link

alectryon.el fails to recognize roles which are visible for a sphinx project #6

Open jhaag opened 4 years ago

jhaag commented 4 years ago

Within our documentation we are making use of the :ref: role and the :download: role quite heavily. Unfortunately, alectryon.el seems to mark uses of these text-roles as errors (with messages like 'Unknown interpreted text role "ref"') when in the reST view for a .v file with (*| |*) comment blocks.

I'm not very familiar with how alectryon.el is written, but my assumption is that it is simply creating a buffer and transliterating the .v file into it's (isomorphic) .rst form within that buffer. If this is the case, this issue is even more confusing because opening the tangled file manually in emacs (and thus loading the ReST mode directly) doesn't cause the errors to appear.

cpitclaudel commented 3 years ago

Sorry, looks like I never replied to this? :/

Opening a reST file doesn't cause any checker to run, by default (unless you have Flycheck enabled); even if you do have Flycheck enabled, it will run Sphinx in addition to reST, and the Sphinx checker will know about Sphinx roles.

The checker that alectryon.el uses by default runs plain docutils/rest, not Sphinx; hence the issue. The fix would be to look for "conf.py" and if found to use a Sphinx checker instead of the docutils one.

jhaag commented 3 years ago

Thanks for the guidance on this issue. I haven't had time to work on adding new content to our documentation recently, so I can't say whether or not this is still a behavior that I'm observing. However, I now have a path forwards in terms of debugging it if it arises again.