Fortran support

[awvwgk]

Currently, breathe will pass Fortran classes (derived types), namespaces (modules), procedures, ... as C++ code and sphinx will complain about the invalid syntax. Integrating Fortran code documentation in sphinx would be a big feat for the @fortran-lang community as we are migrating most of the user documentation to sphinx and so far breathe seems one of the best available options for this purpose.

Related

• sphinx-fortran, based on numpy.f2py.crackfortran
• similar request for Java support in https://github.com/michaeljones/breathe/issues/778.

[michaeljones]

Thanks for raising the issue @awvwgk. It would certainly be interesting to see Breathe be used for more languages.

Is there any centralised funding available for this effort or is it community driven? This project is maintained but we don't have a lot of spare time and we're keen to see the project become more sustainable if possible.

[awvwgk]

We could ask in the Fortran community discourse whether there is interest from volunteers or possibility for funding. I already opened a thread at https://fortran-lang.discourse.group/t/3506.

[michaeljones]

Great, thanks. Interested to see where it goes.

You should be aware that for very large projects there have been some performance issues with Breathe in its current form. They have improved over time and I'm not 100% sure of the current stats but it is well worth testing out at a large scale if you can. Though how you can do that when it isn't fully supported, I'm not sure.

[awvwgk]

I have a ~40k LOC project in mind which I want to apply breathe to (Fortran, C and Python), this is usually considered medium-sized at most in the Fortran ecosystem.

[vermeeren]

@awvwgk Something that might be useful when/if adding Fortran support to Breathe is #550 , which added C# support also using an external domain.

[K20shores]

@michaeljones it would be great to see this happen. I know that fortls can read doxygen comments to produce intellisense for editors. Perhaps using their engine could ease the pain of implementing this. I had started a repo (which I've done nothing with) to try that out. I'm very interested in making this happen. Would leveraging fortls be in line with how the breathe project may want to do this or should I consider going ahead with making a separate package?

[michaeljones]

I don't want to count out using other sources of information for Breathe (beyond Doxygen that is) and maybe language servers can provide to correct kind of information but it isn't something that had previously crossed my mind.

I'm afraid my status has not changed since my earlier post. We are keen that the project is well funded and becomes more sustainable. Those of us who have been primarily writing and maintaining Breathe currently struggle to make time to work on it for free.

If you or any associated company or organisation are in a position to contribute to funding the project please let us know.

[saadrahim]

Please reach out to me at saad.rahim afdsafa @ amd.com (remove the random strings in between). I would like to discuss how to arrange to implement this feature.

[michaeljones]

I have reached out to saadrahim and would be happy to discuss this further.

I've done some research into the language server angle. It does look promising to some degree but has its flaws too. It is possible to ask a language server for the symbols in a particular file and so one might imagine that this could help us locate symbols but then the information returned is limited as far as per-symbol info and the language server's main feature for returning documentation is the 'hover' query which is named after the idea of "I'm hovering over a symbol in my editor, please give me some text to put in a pop-up". Based on some conversations with more experienced people and the types in the language server spec, it seems like the response to the 'hover' query is a fairly generic blob of text with no particular consistent structure or formatting between implementations.

It could be that for any particular language and language server implementation it would be possible to assemble some good looking docs from the response but it might require tweaking between languages and it might be lacking in other ways.

It would be interesting to explore, and I aim to have a look eventually, but other sources might be more reliable for documentation generation.

As an update on previous messages, I've started doing a re-write of Breathe using Rust to try to tackle some of the performance and memory issues. It is currently somewhere between alpha and beta status. The aim is to put it out under a more restrictive license (Parity Public License) with the intent that companies should pay for a separate commercial license and so support the project if they want to use it on closed source code bases.