User-facing documentation

[melissawm]

I'd like to suggest a difference between user-facing documentation (Tutorials, How-tos) and Reference/API docs. In #4 , most of the comments apply to Reference, but I don't see mentions of user-facing documentation. Are you interested in that?

I'm working for a few months at the Documentation Team for NumPy, and we have been using the concepts described in this article which has been extremely helpful in organizing and writing new docs for NumPy. For reference, we also wrote a NumPy Enhancement Proposal to elaborate on it.

I'm not saying stdlib should go in the same direction; that's for the community to decide. But I'd like to propose a discussion on whether the community wants this kind of content, how to organize it and how can we contribute to it.

This kind of documentation can be done with Sphinx, github pages or some other tool; Sphinx has the disadvantage of being a bit cumbersome in syntax, but it's easy to use it to integrate with the API documentation (including cross-linking etc). Markdown is easier and allows for other people to contribute with a lower barrier of entry.

What I'm proposing in this issue is

• A discussion around the best tool (even if temporary) for writing user-facing documentation for stdlib
• Which documents are high priority that people could start writing right now.

[certik]

@melissawm thank you for proposing it. For sure we want a nice user facing documentation.

I recently learned of this project:

https://myst-parser.readthedocs.io/

Which allows you to use Sphinx, but with Markdown syntax! I've been looking for something like that for years. I haven't tried it yet, but I am hoping it will work great.

So I am going to try it and set it up, and if it works, I propose we use that. As that way we can just use Markdown.

[ghwilliams]

Hi I can help writing some tutorials using stdlib. What tools do I need to use? I can start writing the fortran codes (necessary for the tutorials) and the text in simple MS Word.

[certik]

@ghwilliams awesome, thank you! Write it in Markdown and put it into our wiki: https://github.com/fortran-lang/stdlib/wiki

Then as we setup a website / Sphinx, we can easily port it.

[ghwilliams]

Great. I will try it.

[zbeekman]

The FORD documentation is getting deployed now. We could try writing user-facing, prose-like documentation in the FORD pages directory. Please see the "Writing Pages" documentation on the FORD wiki.

I am open to other ideas too, but consolidating things in one place might be nice. Also, anyone who wants to help keep FORD maintained/up-to-date is welcome to help out.

[milancurcic]

Yes, I think this is the way to go. Having the user-facing docs and the API-like docs under the same system will make it easier to maintain.

[certik]

In the long run, can FORD become a plug into Sphinx? Sphinx has many more contributors (https://github.com/sphinx-doc/sphinx/). FORD could be used to handle extracting the documentation out of Fortran, and Sphinx for the rest, together with the Markdown parser for Sphinx I mentioned above (https://myst-parser.readthedocs.io/), if it works. There are additional features that you want to use (I would argue), such as citations, cross references, label math equations, pdf export, etc. The Sphinx / myst-parser supports that, but FORD doesn't seem so.

This would have the advantage that we don't have to maintain our own documentation tool. We can still have our own template / style.

It might be too much work to get it working with Sphinx and thus not worth it, but the motivation to maintain our own documentation tool should be better explained I feel. We already have to develop and maintain so many tools around Fortran, that I feel it would be very helpful to piggy back on Sphinx and have one less thing to worry about.

Also, if FORD is to become our main tool to handle documentation, I would recommend to relicense it to MIT or BSD to be compatible with the rest of the tools that we are trying to develop for Fortran (and generally compatible with the Python ecosystem also).

[milancurcic]

Also, if FORD is to become our main tool to handle documentation, I would recommend to relicense it to MIT or BSD to be compatible with the rest of the tools that we are trying to develop for Fortran (and generally compatible with the Python ecosystem also).

Does this matter if we're not distributing the source or linking to it? We're using it as a tool in CD.

@cmacmackin are you open to relicensing? We've talked about this before and I know you like GPL, but some time has passed.

[certik]

Does this matter if we're not distributing the source or linking to it?

First of all I think we should distribute it as part of FPM so that users can build documentation of their projects (probably as a Conda package that FPM will simply install).

It does not technically matter right now. But it might in the future, and we might want to reuse some code from it in other projects as well as distribute it, and these relicensing efforts are best done at the beginning, otherwise it becomes a nightmare later, because you have to ask each contributor for a permission. Furthermore, I think we should play nicely with the Python ecosystem, FORD being a Python package, so I suggest to read this "BSD pitch" from the author of Matplotlib:

http://nipy.sourceforge.net/nipy/stable/faq/johns_bsd_pitch.html

as he says, we want to make it easy for companies to use our work and to embrace Fortran. If FORD becomes the documentation tool for Fortran, companies will sooner or later start asking about the GPL license, and by being MIT or BSD, it's one less obstacle to worry about. (I am well aware that GPL allows commercial distribution, but I am also aware that lawyers in big corporations must analyze and approve or deny each case.)

[cmacmackin]

In the long run, can FORD become a plug into Sphinx?

I've actually been thinking about this a bit already and it probably is the right way to go. No immediate plans to work on it, however.

Also, if FORD is to become our main tool to handle documentation, I would recommend to relicense it to MIT or BSD to be compatible with the rest of the tools that we are trying to develop for Fortran (and generally compatible with the Python ecosystem also).

Absolutely not. I am a firm believer in the GPL. If I were to spin off some of FORD into a library then I would be open to releasing that under the LGPL, but that is as permissive as I'll get. Even that may be difficult in practice, however, as there are a number of other contributors to FORD who never assigned their copyright to me and would thus have to agree to the change.

I am willing to accept that this could mean you won't be able to reuse FORD code in other tools (unless they're willing to go GPL). However, there is absolutely nothing to stop you from running or packaging FORD. If you refuse to package GPL code then you will be denying yourself some very good software, such as FFTW3, which doesn't seem sensible to me.

GPL shouldn't be a serious impediment to companies running FORD. After all, the most popular compiler out there (GCC) is under a GPL license.

[milancurcic]

The way we're using FORD right now, I think it's okay. However, @certik's points are valid and we can't anticipate how we'd want to work and/or distribute the documentation system in the future. For this reason, we should start looking into alternatives immediately: Sphinx + Myst? Mkdocs? Readthedocs?

Btw, even packaging FORD would be problematic, the way we're designing fpm now. As far as I understand this, If FORD is pulled as a Conda binary distribution, we have to also bring in the source, and the whole parent package needs to be GPL'd. So I personally don't think we should go down this road.

[cmacmackin]

I can't speak for the legalities of Conda distributions as I don't know much about how they work. However, in general it is not necessary to distribute a copy of the source code with binary, so long as the source code is publicly accessible and instructions are provided to access it (section 6e of the licence):

... If the place to copy the object code is a network server, the Corresponding Source may be on a different server (operated by you or a third party) that supports equivalent copying facilities, provided you maintain clear directions next to the object code saying where to find the Corresponding Source....

I can't remember off the top of my head whether FORD would include any such instructions at present, but I'd be happy to add them.

I note that distributing GPL code in a Conda binary is already done in the case of FFTW3.

[zbeekman]

I hope my efforts weren't in vain. I still don't fully understand why we can't LGPL it (under v2) as Chris mentioned. It's a tool (or plug in to a tool) so we should be able to find a way to use an LGPL version, no? There won't be any runtime dependency, and the docs that it generates are under whatever license the user wants.

[cmacmackin]

Found an FAQ entry which seems to address this: https://www.gnu.org/licenses/gpl-faq.en.html#MereAggregation

It shouldn't be an issue.

[certik]

Thanks @cmacmackin for explaining your view. You should choose the license that you see fit for FORD, and just to make clear, I am not questioning your choice of license for your library. That's why I didn't post this comment in the FORD repository. I very strongly believe that if you start a library and do all the work, you have every right to choose any license you want.

In the same way, for fortran-lang repositories and the related tools, I very strongly believe it is best for the community and the ecosystem if we use permissive licenses and I explained the reasons above.

Beyond licensing, I do not think we should be maintaining a general documentation / website generator. Rather, we should pick a well maintained tool and only maintain a plugin to extract comments from Fortran source codes. As Milan mentioned, Sphinx + Myst, Mkdocs, Readthedocs are all options we should explore. They have large communities.

@zbeekman your efforts were not in vain. We have something to get started and that is always important.

[zbeekman]

I just hope we can find/make something with Fortran support that is as good as FORD's is. I'm doubtful we'll find anything with first class Fortran support. I still don't fully understand why an LGPL version of FORD couldn't be turned into a Sphinx plugin and used. But ¯_(ツ)_/¯

[certik]

Right now FORD seems to be the best tool there is, so that's why we are using it (I am a big fan of having something even if imperfect, rather than nothing). That does not mean it must necessarily be the best approach in the long run, as discussed above.

All I am asking is that we keep our options open.

[zbeekman]

EDIT: I left out a word or two

I'm completely open to that. If there's something more appropriate and close to as good or better than FORD, then sign me up! (I just haven't seen it yet.)