Stdlib user documentation

Announcements
1

I started building a scaffold for the stdlib user documentation based on what we already have for fpm. The infrastructure is similarly based on sphinx and myst:

Now we need some content, I’m looking for both contributors and ideas for this. I already have some potential topics:

  • complete walk-through tutorials for example applications based on stdlib modules
    • statistics, distributions
    • string processing, input/output
    • quadrature, mathematical utilities
  • recipes for problems solved by stdlib
    • converting integer/real values to strings with to_string
    • reading a npy file, perform calculations in Fortran and dump it back in npy format
    • sorting and searching a list of strings
    • reading a whole file into a string or list of strings
    • working on bytes or bitarrays using the bitsets types (instead of unsigned arithmetic)

Similar to the fpm docs the structure of the topics is following the Diátaxis framework (briefly summarized: tutorials are self-contained guides to allow learning by doing, recipes are problem-oriented examples to solve common tasks).

Further, there is also a design and a specification section, which can be populated. There was a suggestion to collect prior discussions on stdlib conventions in the design section and link to the respective issues in the tracker on GitHub.

Like the fpm docs translations are possible, but we need some content first before it makes sense to translate the pages. If you like to translate, please consider contributing to the content first, I found it really useful to work on both content and translation when starting with the fpm docs. Also, if you already have localized content on stdlib, we can translate it to English and add the translation as well.

Let me know if you need any help with the technical setup. All contributions, feedbacks and ideas are very welcome.

12 Likes
2

The FortranTip Twitter channel, after covering more of the language, such as OOP, coarrays, and C interoperability, will cover the use of libraries such as stdlib. A tweet is limited to 257 characters of text plus 23 for a link (possibly to a demonstration code or a tutorial). Tips about stdlib and other open-source libraries are welcome. I may write some and post them here for feedback.

SciPyTip has attracted 135K followers with short tips such as

If you need to compute a binomial coefficient with integer arguments exactly, use scipy.special.comb with exact=True.

My preference would be to post longer tips with links to demonstration codes, even if that entails a lower frequency of posts.

3

Good idea, I just pushed some recipes on handling npy data with stdlib (Reading and writing npy files — Fortran Standard Library), which should be short enough to be useful for posting via @FortranTip.

2 Likes
4

There is a pretty detailed Building stdlib from source HowTo but I couldn’t find how to actually get the source. I know it can be found elsewhere but I’d guess such a HowTo should start with getting the source. Or, maybe, I have missed it?

5

Good point, I added a section on obtaining the source code from the GitHub repository.