Integration with Sphinx

[astroDimitrios]

It would be nice if Ford had a way to easily integrate its API docs with Sphinx based user docs. Will get back to this when I'm home from RSECon!

[clatim]

Did you get anywhere? I would be interested in helping with this.

[p-costa]

There's also this discussion started by @jalvesz.

[ZedThree]

I think there's basically two parts to getting this working:

1. Creating a set of Sphinx classes for rendering the docs
   • This would let users manually write docs in Sphinx
   • Sphinx tutorial on reference domains -- unfortunately rather brief!
   • There is already one fortran sphinx extension, although I found it rather fragile and incomplete. It also has an unusual licence that might mean building on top of it rather difficult. Probably worth looking into though!
2. Converting Ford classes into the relevant Sphinx classes
   • This would then let us do the automatic conversion

A third aspect might be converting the existing Ford HTML templates into a roughly equivalent Sphinx theme.

Step 1 would let us manually write something like:

.. fortran:function: foo

   Some function foo

   :param integer, intent(in) a: first argument
   :param integer, intent(inout) b: second argument
   :return: the foo of a and b
   :rtype: integer

and step 2 would convert Ford classes into that text.

@jalvesz, @clatim, @astroDimitrios if you're all still interested in working on this, I'd be happy to give you write access to the repo so we could better collaborate -- maybe we have a call in the new year to discuss? My email is in my profile if you want to get in touch.

[jalvesz]

I had indeed started to work on this here https://github.com/jalvesz/fspx (I just made it public to help this discussion) it is in a very drafty state and currently doesn't use FORD but fparser2 as the backend. I wouldn't mind at all dropping that project in order to improve FORD to make it a sphinx extension.

GitHub

GitHub - jalvesz/fspx

Contribute to jalvesz/fspx development by creating an account on GitHub.

[astroDimitrios]

@ZedThree I would still like to help with this, you have my email and a meeting in the new year sounds good :)

[ZedThree]

@jalvesz @clatim if you're still interested in this, please get in touch and we'll set up a call about how best to go about this :)

[jalvesz]

@ZedThree yes, I just sent you an email :)

[jalvesz]

Hello @ZedThree @astroDimitrios I wanted to let you know that @MilanSkocic managed to use FORD as dependency in fspx https://github.com/jalvesz/fspx/blob/main/src/fspx/fortran_parser.py. The fparse2 dependency has been removed in favor of FORD.

GitHub

fspx/src/fspx/fortran_parser.py at main · jalvesz/fspx

Contribute to jalvesz/fspx development by creating an account on GitHub.

[ZedThree]

Awesome!